actionagent 1.8.1 → 1.9.0

data/app/services/action_agent/sandbox_manifest.rb

@@ -2,29 +2,57 @@
 
 module ActionAgent
   # The runtime manifest: how a booted checkout tells the sandbox backend
-  # where its MCP facade answers and which bearer token opens it.
+  # where its MCP facade answers and which bearer token opens it, and which
+  # of the app's models an assistant could be given tools over.
   #
-  #   { "mcp_path": "/activeagents/mcp", "mcp_token": "aa_..." }
+  #   { "mcp_path": "/activeagents/mcp", "mcp_token": "aa_...",
+  #     "models": [{ "name": "Reservation", "table": "reservations",
+  #                  "columns": [{ "name": "status", "type": "string" }] }] }
   #
   # The checked-out app writes it with `bin/rails action_agent:sandbox:manifest`
   # (it mounts this engine, so the task ships with it), and a backend reads it
   # back with .parse. Both halves live here so they cannot drift.
+  #
+  # Writing it also mirrors the checkout's agent classes into its dashboard
+  # (AgentSync), so the facade serves their run_<slug> tools to the key it
+  # names. The key and the agents each belong to the only record of the class
+  # their model is owned through, when there is exactly one (see
+  # .sandbox_owner), and to nobody in an app with no owner model.
   module SandboxManifest
     # Where the manifest task writes, when set; stdout otherwise.
     PATH_ENV = "ACTION_AGENT_SANDBOX_MANIFEST"
+    MAX_MODELS = 200
+    MAX_COLUMNS = 150
+    # The namespaces of models an app gets from Rails and these gems rather
+    # than writes itself.
+    FRAMEWORK_NAMESPACES = %w[ActionAgent:: SolidAgent:: ActiveAgent:: ActiveStorage:: ActionText:: ActionMailbox:: ActiveRecord::].freeze
     # The dashboard API key the manifest hands out, created once per checkout.
     KEY_NAME = "Checkout sandbox runtime"
+    # Column names that look like they hold a credential:
+    # ActiveAgent::SchemaTools::SECRET_COLUMNS, or the same pattern under a
+    # framework release that predates the constant, which an app can bundle
+    # beside this engine.
+    SECRET_COLUMNS =
+      if defined?(ActiveAgent::SchemaTools) && ActiveAgent::SchemaTools.const_defined?(:SECRET_COLUMNS, false)
+        ActiveAgent::SchemaTools::SECRET_COLUMNS
+      else
+        /password|digest|token|secret|api_key|otp|encrypted|ssn/i
+      end
 
     class Error < StandardError; end
 
     module_function
 
     # Builds the manifest inside the booted app: the engine's MCP path under
-    # wherever the app mounts it, and an API key for the MCP facade.
+    # wherever the app mounts it, and an API key for the MCP facade. Also
+    # syncs the app's agent classes. A class that cannot be synced is
+    # reported on stderr, and the manifest is written regardless.
     #
     # @param routes [ActionDispatch::Routing::RouteSet] the app's routes
+    # @param agent_classes [Array<Class>, nil] what to sync; nil for
+    #   .checkout_agent_classes
     # @return [Hash{String => String}]
-    def generate(routes: Rails.application.routes)
+    def generate(routes: Rails.application.routes, agent_classes: nil)
       # Rails 8 loads routes lazily in development and test; the mount is
       # invisible until they are.
       Rails.application.reload_routes_unless_loaded if Rails.application.respond_to?(:reload_routes_unless_loaded)
@@ -32,21 +60,132 @@ module ActionAgent
       mount = ActiveAgent::Telemetry::Configuration.new.mount_path_in(routes)
       raise Error, "ActionAgent::Engine is not mounted in this app's routes" if mount.nil?
 
-      { "mcp_path" => "#{mount}/mcp", "mcp_token" => api_key.token }
+      key = api_key(sandbox_owner(ActionAgent::ApiKey))
+      sync_agents(agent_classes || checkout_agent_classes, sandbox_owner(ActionAgent::Agent))
+      { "mcp_path" => "#{mount}/mcp", "mcp_token" => key.token, "models" => app_models }
+    end
+
+    # The app's own models under app/models that have a table, each with its
+    # columns but +id+ and those that look like secrets (SECRET_COLUMNS), at
+    # most MAX_MODELS models of MAX_COLUMNS columns. Empty when they cannot
+    # be loaded, which is reported on stderr.
+    #
+    # @return [Array<Hash>] [{ "name" =>, "table" =>, "columns" => [{ "name" =>, "type" => }] }]
+    def app_models(root = Rails.root.join("app", "models"))
+      return [] unless defined?(ActiveRecord::Base) && root.directory?
+
+      begin
+        Rails.autoloaders.main.eager_load_dir(root.to_s)
+      rescue StandardError, ScriptError => e
+        warn "[ActionAgent] sandbox manifest: could not load app/models: #{e.class}: #{e.message}"
+      end
+
+      roots = [ root.to_s, File.realpath(root) ].uniq.map { |dir| "#{dir.chomp("/")}/" }
+      models = ActiveRecord::Base.descendants.select { |klass| app_model?(klass, roots) }.sort_by(&:name).first(MAX_MODELS)
+      models.filter_map do |klass|
+        columns = klass.columns.reject { |column| column.name == "id" || SECRET_COLUMNS.match?(column.name) }
+        { "name" => klass.name, "table" => klass.table_name,
+          "columns" => columns.first(MAX_COLUMNS).map { |column| { "name" => column.name, "type" => column.type.to_s } } }
+      rescue StandardError => e
+        warn "[ActionAgent] sandbox manifest: could not read #{klass.name}'s columns: #{e.class}: #{e.message}"
+        nil
+      end
+    end
+
+    def app_model?(klass, roots)
+      return false if klass.name.blank? || klass.abstract_class? || klass.name.include?("HABTM_")
+      return false if FRAMEWORK_NAMESPACES.any? { |namespace| klass.name.start_with?(namespace) }
+
+      file, = Object.const_source_location(klass.name)
+      file && roots.any? { |dir| file.start_with?(dir) || File.realpath(file).start_with?(dir) } && klass.table_exists?
+    rescue NameError, SystemCallError, ActiveRecord::ActiveRecordError
+      false
     end
 
     # The checkout's own dashboard API key for the facade. Reused across
-    # runs so a re-run manifest does not mint a key per boot. A host that
-    # owns keys by account or user gets a key with no owner, which reaches
-    # no agents over MCP — the manifest says so rather than failing.
-    def api_key
-      ActionAgent::ApiKey.find_or_create_by!(name: KEY_NAME)
+    # runs so a re-run manifest does not mint a key per boot. A key without
+    # an owner takes +owner+ when there is one. In an app that owns keys by
+    # account or user and has no single owner, the key has none and reaches
+    # no agents over MCP.
+    def api_key(owner = nil)
+      key = ActionAgent::ApiKey.find_or_initialize_by(name: KEY_NAME)
+      key.owner = owner if owner && key.owner.nil?
+      key.save! if key.new_record? || key.changed?
+      key
+    end
+
+    # The record the checkout's +model+ rows belong to: the only one of the
+    # class +model+ is owned through. The API key and the agents can be owned
+    # through different classes (an account and a user), so each is resolved
+    # on its own. Nil when the app configures no owner class for +model+, and
+    # when that class has no record or several, since a sandbox cannot tell
+    # whose it would be.
+    #
+    # @param model [Class] an Ownable model
+    # @return [ActiveRecord::Base, nil]
+    def sandbox_owner(model)
+      owner_class = owner_class_for(model)
+      return nil if owner_class.nil?
+
+      owners = owner_class.limit(2).to_a
+      owners.first if owners.one?
+    end
+
+    def owner_class_for(model)
+      association = model.owner_association
+      association && ActionAgent.public_send(Ownable::CLASS_FOR.fetch(association)).safe_constantize
     end
 
-    # Reads a manifest a checkout wrote.
+    # The app's own agent classes: those defined under app/agents, except
+    # ApplicationAgent and abstract ones.
+    #
+    # @param root [Pathname] where the app keeps its agents
+    # @return [Array<Class>]
+    def checkout_agent_classes(root = Rails.root.join("app", "agents"))
+      return [] unless defined?(ActiveAgent::Base) && root.directory?
+
+      loader = Rails.autoloaders.main
+      Dir[root.join("**", "*.rb").to_s].sort.each do |path|
+        loader.load_file(path)
+      rescue StandardError, ScriptError => e
+        warn "[ActionAgent] sandbox manifest: could not load #{path}: #{e.class}: #{e.message}"
+      end
+
+      roots = [ root.to_s, File.realpath(root) ].uniq.map { |dir| "#{dir.chomp("/")}/" }
+      ActiveAgent::Base.descendants.select do |klass|
+        next false if klass.name.blank? || klass.abstract? || klass.name == "ApplicationAgent"
+
+        file, = Object.const_source_location(klass.name)
+        file && roots.any? { |dir| file.start_with?(dir) || File.realpath(file).start_with?(dir) }
+      rescue NameError, SystemCallError
+        false
+      end.sort_by(&:name)
+    end
+
+    # Syncs each class on its own, so one that cannot be synced (a provider
+    # gem the checkout lacks, say) leaves the rest synced.
+    def sync_agents(classes, owner)
+      if owner.nil? && ActionAgent::Agent.owner_association
+        warn "[ActionAgent] sandbox manifest: no agents synced: the app owns agents by " \
+          "#{owner_class_for(ActionAgent::Agent)&.name || "an owner model"} and has no single owner for a sandbox to use"
+        return
+      end
+
+      classes.each do |klass|
+        result = ActionAgent::AgentSync.call([ klass ], owner: owner)
+        warn "[ActionAgent] sandbox manifest: could not sync #{klass.name}: #{result.errors}" unless result.success?
+        result.skipped.each { |row| warn "[ActionAgent] sandbox manifest: skipped #{row.skipped}" }
+      rescue StandardError => e
+        warn "[ActionAgent] sandbox manifest: could not sync #{klass.name}: #{e.class}: #{e.message}"
+      end
+    end
+
+    # Reads a manifest a checkout wrote. Its "models" are kept as far as they
+    # have the shape .app_models gives them: an entry that does not is
+    # dropped, and a manifest written before the list existed has none.
     #
     # @param json [String]
-    # @return [Hash{String => String}] with "mcp_path" and "mcp_token"
+    # @return [Hash] with "mcp_path", "mcp_token" and "models"
     def parse(json)
       data = JSON.parse(json.to_s)
       raise Error, "the manifest is not a JSON object" unless data.is_a?(Hash)
@@ -59,9 +198,23 @@ module ActionAgent
       token = data["mcp_token"]
       raise Error, "the manifest's mcp_token is not a string" unless token.nil? || token.is_a?(String)
 
-      { "mcp_path" => path, "mcp_token" => token }
+      { "mcp_path" => path, "mcp_token" => token, "models" => parse_models(data["models"]) }
     rescue JSON::ParserError => e
       raise Error, "the manifest is not JSON (#{e.message.truncate(120)})"
     end
+
+    def parse_models(value)
+      Array(value).first(MAX_MODELS).filter_map do |entry|
+        next unless entry.is_a?(Hash) && SandboxBootSpec::MODEL_NAME.match?(entry["name"].to_s)
+
+        columns = Array(entry["columns"]).first(MAX_COLUMNS).filter_map do |column|
+          next unless column.is_a?(Hash) && SandboxBootSpec::COLUMN_NAME.match?(column["name"].to_s)
+          next if SECRET_COLUMNS.match?(column["name"])
+
+          { "name" => column["name"], "type" => column["type"].to_s.truncate(32) }
+        end
+        { "name" => entry["name"], "table" => entry["table"].to_s.truncate(128), "columns" => columns }
+      end
+    end
   end
 end

data/app/services/action_agent/sandbox_orchestrator.rb

@@ -47,10 +47,31 @@ module ActionAgent
       # Claude Code sessions inside an app_runtime checkout. Optional: a
       # backend without them simply cannot run sessions (see #supports?).
       code_session: %i[run_code_session],
-      cancel_code_session: %i[cancel_code_session]
+      cancel_code_session: %i[cancel_code_session],
+      # Optional too, each documented on the orchestrator method of the same
+      # name. A backend implements a verb by defining a public method with
+      # that name and signature.
+      changed_files: %i[changed_files],
+      read_file: %i[read_file],
+      start_browser: %i[start_browser],
+      stop_browser: %i[stop_browser],
+      resume_boot: %i[resume_boot],
+      boot_status: %i[boot_status],
+      boot_log: %i[boot_log],
+      start_claude_login: %i[start_claude_login],
+      submit_claude_login_code: %i[submit_claude_login_code],
+      claude_login_status: %i[claude_login_status],
+      claude_logout: %i[claude_logout],
+      refresh_runtime: %i[refresh_runtime]
     }.freeze
 
+    # What #start_browser may be asked for: a browser with no window, or one
+    # a person can watch where the backend can show one.
+    BROWSER_MODES = %i[headless headed].freeze
+
     class UnsupportedBackendError < StandardError; end
+    # A host-registered backend failed a sign-in verb (see #login_call).
+    class BackendError < StandardError; end
 
     # All backend names available in this install.
     def self.backends
@@ -85,38 +106,45 @@ module ActionAgent
 
     attr_reader :backend_name
 
+    # Login adapters return only flow state / the CLI authorize URL. No
+    # credential, terminal output or echoed code may cross this boundary.
+    # Whatever a host-registered backend raises comes out as BackendError,
+    # which callers rescue along with the local backend's own errors.
+    def start_claude_login(sandbox) = login_call { @backend.public_send(adapter_method(:start_claude_login), sandbox) }
+    def submit_claude_login_code(sandbox, code) = login_call { @backend.public_send(adapter_method(:submit_claude_login_code), sandbox, code) }
+    def claude_login_status(sandbox) = login_call { @backend.public_send(adapter_method(:claude_login_status), sandbox) }
+    def claude_logout(sandbox) = login_call { @backend.public_send(adapter_method(:claude_logout), sandbox) }
+    def refresh_runtime(sandbox) = @backend.public_send(adapter_method(:refresh_runtime), sandbox)
+
     # Create a new sandbox for the given session
     #
     # @param sandbox_session [SandboxSession] The session to create a sandbox for
     # @param instance_tier [String, Symbol, SandboxInstanceTier] Optional instance tier
+    # @param boot_config [SandboxBootSpec, Hash, nil] how to boot the checkout
+    #   instead of its own .activeagents/sandbox.yml, handed to the backend as
+    #   SandboxBootSpec#to_h. A backend whose create method takes no
+    #   boot_config: keyword boots as it always has; one that must apply
+    #   (apply "always") is refused there instead.
     # @return [Hash] Sandbox details including ID/name and URL
-    def create_sandbox(sandbox_session, instance_tier: nil)
+    # @raise [UnsupportedBackendError] for a spec that must apply and a backend
+    #   that cannot take one
+    # @raise [SandboxBootSpec::Invalid] for a malformed spec
+    def create_sandbox(sandbox_session, instance_tier: nil, boot_config: nil)
       # Resolve tier
       tier = resolve_tier(instance_tier)
+      spec = SandboxBootSpec.wrap(boot_config)
 
       method = adapter_method(:create)
-      result = if accepts_instance_tier?(method)
-        @backend.public_send(method, sandbox_session, instance_tier: tier)
-      else
-        @backend.public_send(method, sandbox_session)
+      options = {}
+      options[:instance_tier] = tier if accepts_instance_tier?(method)
+      if spec && accepts_keyword?(method, :boot_config)
+        options[:boot_config] = spec.to_h
+      elsif spec && !spec.without_engine_only?
+        raise UnsupportedBackendError, "The #{backend_name} sandbox backend cannot boot a checkout from a boot spec"
       end
+      result = @backend.public_send(method, sandbox_session, **options)
 
-      # Normalize response format across backends
-      {
-        sandbox_id: result[:container_name] || result[:pod_name] || result[:job_name],
-        url: result[:url],
-        ip: result[:container_ip] || result[:pod_ip],
-        backend: @backend_name,
-        instance_tier: result[:instance_tier] || tier&.id,
-        resources: result[:resources],
-        hourly_cost: result[:hourly_cost] || tier&.hourly_cost&.to_f,
-        created_at: result[:created_at] || Time.current,
-        # An app_runtime sandbox's backend clones sandbox_session.checkout_spec,
-        # boots the app, and reports where its MCP facade answers (and the
-        # bearer token it expects) so agents can use the checkout's tools.
-        mcp_url: result[:mcp_url],
-        mcp_token: result[:mcp_token]
-      }
+      normalize_created(result, tier)
     end
 
     # List available instance tiers
@@ -191,6 +219,30 @@ module ActionAgent
       ADAPTER_METHODS.fetch(verb).any? { |m| @backend.respond_to?(m) }
     end
 
+    # Whether the backend's create method takes a boot spec (see
+    # #create_sandbox's boot_config:).
+    def accepts_boot_config?
+      accepts_keyword?(adapter_method(:create), :boot_config)
+    end
+
+    # Whether the backend can list a checkout's changes and read each file
+    # now and in the commit the checkout was cloned at: #changed_files, and
+    # #read_file with +base+.
+    def reads_checkouts?
+      supports?(:changed_files) && reads_checkout_commit?
+    end
+
+    # Whether the backend's read_file takes +base:+. A backend written before
+    # +base:+ existed defines read_file(session, path) and cannot be asked
+    # for the commit cloned at.
+    def reads_checkout_commit?
+      return false unless supports?(:read_file)
+
+      @backend.method(adapter_method(:read_file)).parameters.any? do |type, name|
+        type == :keyrest || type == :rest || (type.in?(%i[key keyreq]) && name == :base)
+      end
+    end
+
     # Existing backends predate runner selection and support Claude only.
     # A backend must explicitly advertise Codex before accepting its keys.
     def supports_code_runner?(runner)
@@ -212,6 +264,12 @@ module ActionAgent
       end
       refusal = ClaudeCodeAuth.backend_refusal(self) unless runner == "codex"
       raise UnsupportedBackendError, refusal if refusal
+      if runner == "claude_code" && code_session.try(:credential_mode) == "sandbox_login"
+        unless sandbox_session.claude_login_user_id.present? && sandbox_session.claude_login_user_id == code_session.user_id &&
+            claude_login_status(sandbox_session).slice(:logged_in, :auth_method) == { logged_in: true, auth_method: "claude.ai" }
+          raise UnsupportedBackendError, "This user's Claude subscription is no longer signed in to this sandbox"
+        end
+      end
 
       @backend.public_send(adapter_method(:code_session), sandbox_session, code_session, &on_event)
     end
@@ -221,6 +279,156 @@ module ActionAgent
       @backend.public_send(adapter_method(:cancel_code_session), sandbox_session, code_session)
     end
 
+    # The files +sandbox_session+'s checkout has changed since it was cloned,
+    # read without running anything the checkout controls (no git hooks,
+    # filters or configuration from the checkout).
+    #
+    # @return [Hash] { base_commit:, files: }
+    #   base_commit: the commit the checkout was cloned at
+    #   files: one Hash per changed path, each
+    #     path:   relative to the checkout root
+    #     status: "added", "modified" or "deleted"
+    #     mode:   "100644", "100755", "120000" (a symlink) or "160000" (a
+    #             submodule, or a nested repository); nil when deleted
+    #     base_mode: the mode in the commit cloned at, where the backend
+    #             knows it (optional); nil when added
+    #     size:   the bytes in the working tree, where the backend knows them
+    #             (optional); nil when deleted
+    #   Files the repository ignores are not listed.
+    # @raise [UnsupportedBackendError] when the backend does not implement it
+    def changed_files(sandbox_session)
+      @backend.public_send(adapter_method(:changed_files), sandbox_session)
+    end
+
+    # The current content of +path+ in +sandbox_session+'s checkout, or with
+    # +base+ its content in the commit the checkout was cloned at. A symlink
+    # is read as its target path, never followed.
+    #
+    # A backend implements this as read_file(sandbox_session, path, base:),
+    # and is passed +base+ only when it is true.
+    #
+    # @param path [String] relative to the checkout root
+    # @return [String, nil] the bytes, binary-encoded; nil when nothing is
+    #   there
+    # @raise [ArgumentError] when +path+ is absolute or climbs out of the
+    #   checkout, before the backend is asked
+    # @raise [UnsupportedBackendError] when the backend does not implement
+    #   it, or is asked for +base+ and its read_file takes no +base:+ (see
+    #   #reads_checkout_commit?)
+    def read_file(sandbox_session, path, base: false)
+      unless checkout_relative?(path)
+        raise ArgumentError, "#{path.inspect} is not a path inside the checkout"
+      end
+
+      method = adapter_method(:read_file)
+      if base
+        unless reads_checkout_commit?
+          raise UnsupportedBackendError, "The #{backend_name} sandbox backend's read_file takes no base:, " \
+            "so it cannot read the commit a checkout was cloned at"
+        end
+
+        @backend.public_send(method, sandbox_session, path, base: true)
+      else
+        @backend.public_send(method, sandbox_session, path)
+      end
+    end
+
+    # Starts a browser for +sandbox_session+, one per sandbox, and returns how
+    # an agent reaches it over MCP. The backend reads the rest of what it
+    # needs from sandbox_session.browser_launch (see SandboxSession): the
+    # token the browser's MCP endpoint is to expect, the app it may open,
+    # optional tool groups, when to stop, and where to post its recording.
+    #
+    # @param mode [Symbol] one of BROWSER_MODES
+    # @return [Hash] at least { mcp_url:, mcp_token: }: where the browser's
+    #   MCP server answers, and the bearer token it expects (nil for none);
+    #   optionally live_url:, where a person can watch it
+    # @raise [ArgumentError] for a mode outside BROWSER_MODES
+    # @raise [UnsupportedBackendError] when the backend does not implement it,
+    #   or cannot run a browser in +mode+ (see #browser_modes)
+    def start_browser(sandbox_session, mode: :headless)
+      raise ArgumentError, "Unknown browser mode #{mode.inspect}" unless BROWSER_MODES.include?(mode)
+
+      method = adapter_method(:start_browser)
+      unless browser_modes.include?(mode)
+        raise UnsupportedBackendError, "The #{backend_name} sandbox backend cannot show a browser window; start the browser headless"
+      end
+
+      @backend.public_send(method, sandbox_session, mode: mode)
+    end
+
+    # The BROWSER_MODES the backend can start a browser in: what its own
+    # #browser_modes answers, or every mode for a backend that does not say.
+    # Empty when it cannot start a browser at all.
+    #
+    # @return [Array<Symbol>]
+    def browser_modes
+      return [] unless supports?(:start_browser)
+      return BROWSER_MODES.dup unless @backend.respond_to?(:browser_modes)
+
+      BROWSER_MODES & Array(@backend.browser_modes).map(&:to_sym)
+    end
+
+    # Stops +sandbox_session+'s browser. True, also when none was running.
+    #
+    # @raise [UnsupportedBackendError] when the backend does not implement it
+    def stop_browser(sandbox_session)
+      @backend.public_send(adapter_method(:stop_browser), sandbox_session)
+    end
+
+    # Continues a boot of +sandbox_session+ that failed and kept its
+    # workspace, re-running from the step named +from+ (nil for the step that
+    # failed) with the session's current settings.
+    #
+    # @param boot_config [SandboxBootSpec, Hash, nil] the spec to continue
+    #   with, for updated env or secrets; nil for the one the boot started
+    #   with. Passed only to a backend whose method takes the keyword.
+    # @return [Hash] what #create_sandbox returns
+    # @raise [UnsupportedBackendError] when the backend does not implement it
+    def resume_boot(sandbox_session, from:, boot_config: nil)
+      method = adapter_method(:resume_boot)
+      spec = SandboxBootSpec.wrap(boot_config)
+      options = { from: from }
+      options[:boot_config] = spec.to_h if spec && accepts_keyword?(method, :boot_config)
+      normalize_created(@backend.public_send(method, sandbox_session, **options), nil)
+    end
+
+    # How +sandbox_session+'s boot went, step by step, while the backend
+    # still holds it.
+    #
+    # @return [Hash, nil] nil when the backend holds nothing for the session;
+    #   otherwise
+    #     mode:        "config" (the checkout's sandbox.yml) or "spec"
+    #     kind:        the spec's kind, "bootstrap" or "custom"
+    #     failed_step: the name of the step that failed, or nil
+    #     kept:        whether a failed boot's workspace was kept for
+    #                  #resume_boot
+    #     resumable_steps: optional, the step names #resume_boot accepts as
+    #                  `from`
+    #     steps:       [{ name:, status:, started_at:, finished_at:,
+    #                  duration_ms:, detail: }], status one of "pending",
+    #                  "running", "succeeded", "failed" or "skipped"
+    # @raise [UnsupportedBackendError] when the backend does not implement it
+    def boot_status(sandbox_session)
+      @backend.public_send(adapter_method(:boot_status), sandbox_session)
+    end
+
+    # One page of a boot step's log, scrubbed of the session's secrets and
+    # of +secrets+. Pages end at a line break where they can, so a value is
+    # never split between two of them.
+    #
+    # @param step [String] a step name #boot_status lists
+    # @param offset [Integer] the byte offset to read from
+    # @param limit [Integer] the most bytes to read
+    # @return [Hash, nil] { step:, offset:, next_offset:, size:, eof:, text: },
+    #   or nil when the step has no log
+    # @raise [UnsupportedBackendError] when the backend does not implement it
+    def boot_log(sandbox_session, step:, offset: 0, limit: nil, secrets: [])
+      options = { step: step, offset: offset, secrets: secrets }
+      options[:limit] = limit if limit
+      @backend.public_send(adapter_method(:boot_log), sandbox_session, **options)
+    end
+
     # Check if the backend is healthy
     #
     # @return [Boolean] true if backend is reachable
@@ -248,6 +456,17 @@ module ActionAgent
 
     private
 
+    # Runs a sign-in verb, turning a host-registered backend's own errors
+    # into BackendError. The message is kept for the log; the sign-in
+    # endpoints answer with a fixed one.
+    def login_call
+      yield
+    rescue UnsupportedBackendError, LocalSandboxBackend::Error
+      raise
+    rescue StandardError => e
+      raise BackendError, e.message
+    end
+
     # The backend's method for +verb+, or a clear error naming what it
     # would have to implement.
     def adapter_method(verb)
@@ -256,10 +475,45 @@ module ActionAgent
           "#{@backend.class} implements none of #{ADAPTER_METHODS.fetch(verb).join(', ')}")
     end
 
+    # The backend's create result in one shape whichever backend produced it.
+    def normalize_created(result, tier)
+      {
+        sandbox_id: result[:container_name] || result[:pod_name] || result[:job_name],
+        url: result[:url],
+        ip: result[:container_ip] || result[:pod_ip],
+        backend: @backend_name,
+        instance_tier: result[:instance_tier] || tier&.id,
+        resources: result[:resources],
+        hourly_cost: result[:hourly_cost] || tier&.hourly_cost&.to_f,
+        created_at: result[:created_at] || Time.current,
+        # An app_runtime sandbox's backend clones sandbox_session.checkout_spec,
+        # boots the app, and reports where its MCP facade answers (and the
+        # bearer token it expects) so agents can use the checkout's tools.
+        mcp_url: result[:mcp_url],
+        mcp_token: result[:mcp_token],
+        # The models its manifest lists (SandboxManifest.app_models), when the
+        # backend reports them.
+        app_models: result[:app_models]
+      }
+    end
+
+    # Whether +path+ names something inside a checkout: relative, and never
+    # climbing out through "..".
+    def checkout_relative?(path)
+      return false unless path.is_a?(String) && path.present? && !path.include?("\0")
+
+      pathname = Pathname.new(path)
+      pathname.relative? && pathname.each_filename.none?("..")
+    end
+
     def accepts_instance_tier?(method)
       @backend.method(method).parameters.any? { |_type, name| name == :instance_tier }
     end
 
+    def accepts_keyword?(method, keyword)
+      @backend.method(method).parameters.any? { |type, name| name == keyword && %i[key keyreq].include?(type) }
+    end
+
     def resolve_tier(tier_param)
       return nil unless tier_param