actionagent 1.8.0 → 1.9.0

data/config/routes.rb

@@ -71,6 +71,15 @@ ActionAgent::Engine.routes.draw do
       end
     end
 
+    # What paused runs are waiting on a person for, and the answers that
+    # resume them.
+    resources :input_requests, only: [ :index ] do
+      member do
+        post :answer
+        post :decline
+      end
+    end
+
     # Sandboxes. The engine ships the in-memory and local backends; an
     # operator registers the rest (see ActionAgent.sandbox_backends).
     resources :sandboxes, param: :id, only: [ :index, :create, :show, :destroy ] do
@@ -79,6 +88,11 @@ ActionAgent::Engine.routes.draw do
       end
       member do
         post :run
+        # A checkout's boot: its steps, a step's log, and continuing a
+        # failed boot the backend kept.
+        get :boot
+        get :boot_log
+        post :resume_boot
       end
       # Claude Code sessions in an app_runtime sandbox's checkout.
       resources :code_sessions, only: [ :index, :create, :show ] do
@@ -86,6 +100,71 @@ ActionAgent::Engine.routes.draw do
           post :cancel
         end
       end
+      resource :claude_login, only: [ :show, :create, :destroy ], controller: "claude_logins" do
+        post :code
+      end
+      # The checkout's browser (SandboxBrowser), and tickets into its live view.
+      resource :browser, only: [ :show, :create, :destroy ], controller: "sandbox_browsers" do
+        resources :tickets, only: [ :create ], controller: "sandbox_browser_tickets"
+      end
+
+      # A pull request opened from the checkout's changes, its preview, and
+      # the patch to download instead.
+      resource :pull_request, only: [ :show, :create ], controller: "draft_pull_requests" do
+        post :preview
+        get :patch
+      end
+    end
+    get "evaluations/:evaluation_id/runs/:run_id/fixes", to: "evaluation_fixes#index"
+
+    # Projects: a repository booted in a checkout sandbox and evaluated,
+    # with the secrets its boot needs (names only in responses).
+    resources :projects, only: [ :index, :show, :create, :update, :destroy ] do
+      collection do
+        get :capabilities
+        get :preflight
+        get :discover_secrets
+      end
+      member do
+        post :boot
+        get :boot, action: :boot_status
+        get :boot_log
+        get :synced_agents
+        patch :target
+        post :run_evaluation
+      end
+      put :secrets, to: "project_secrets#upsert"
+      resources :secrets, controller: "project_secrets", only: [ :index, :update, :destroy ], param: :name
+      # The setup assistant, the requests for input waiting on the project's
+      # agents, and the models the App assistant may read.
+      post :setup, to: "project_setup#start"
+      post "setup/claude_code", to: "project_setup#fix_with_claude_code", as: :setup_claude_code
+      patch :setup, to: "project_setup#update"
+      get :input_requests, to: "project_setup#input_requests"
+      get :app_models, to: "project_setup#app_models"
+      put :schema_tools, to: "project_setup#schema_tools"
+      # The pull request that installs the engine in the repository.
+      resource :install_pull_request, only: [ :show, :create ], controller: "project_install_pull_requests" do
+        post :preview
+        get :patch
+      end
+
+      # The explorer agent's start, and how the project's browser signs in.
+      resources :explorations, controller: "project_explorations", only: [ :create ]
+      resource :sign_in, controller: "project_sign_ins", only: [ :show, :update, :destroy ] do
+        post :check
+        post :save_browser
+      end
+    end
+
+    # Explorations: candidate scenarios found by walking a project's app,
+    # reviewed and accepted into its evaluation (see Exploration).
+    resources :explorations, only: [ :index, :show, :create ] do
+      member do
+        post :accept
+        post :stop
+        patch "candidates/:candidate_id", action: :update_candidate, as: :candidate
+      end
     end
 
     # Tool inventory — auto-detected from the tool roster each generation
@@ -108,8 +187,17 @@ ActionAgent::Engine.routes.draw do
       end
     end
 
-    resources :session_recordings, only: [ :index, :show, :destroy ] do
+    # create is the Run Agent workbench's recording of a conversation.
+    resources :session_recordings, only: [ :index, :show, :create, :destroy ] do
       member do
+        # A recorder holding the recording's ingest token posts its events
+        # here without a dashboard session; any other post is a dashboard
+        # session's, checked for forgery like the rest of the API.
+        post :events, to: "recording_event_ingest#create",
+          constraints: ->(request) { request.authorization.to_s.match?(/\ABearer\s/i) }
+        post :events, action: :create_events
+        get :events
+        get :timeline
         get :actions
         get "snapshot/:action_id", action: :snapshot, as: :snapshot
         post :export
@@ -123,6 +211,12 @@ ActionAgent::Engine.routes.draw do
       end
     end
 
+    # The sessions a caller can replay, and the timeline of a conversation,
+    # a run or an evaluation scenario's replay, with or without a recording.
+    get "sessions", to: "sessions#index", as: :sessions
+    get "sessions/:kind/:id/timeline", to: "sessions#timeline", as: :session_timeline,
+      constraints: { kind: /context|run|scenario_result/ }
+
     resource :analytics, only: [], controller: "analytics" do
       get "/", action: :index
     end
@@ -142,7 +236,7 @@ ActionAgent::Engine.routes.draw do
 
     # Agent output evaluations. A scenario suite also manages its scenarios
     # here, and exposes each run's per-scenario, per-model results.
-    resources :evaluations, only: [ :index, :show, :create, :destroy ] do
+    resources :evaluations, only: [ :index, :show, :create, :update, :destroy ] do
       member do
         post :run
         get "runs/:run_id", action: :show_run, as: :run_result
@@ -154,6 +248,33 @@ ActionAgent::Engine.routes.draw do
       end
     end
 
+    # Scenario catalogs: YAML catalogs of scenarios (products, sets), imported
+    # from a document, a file or a connected repository, exported as YAML,
+    # synced to Active Storage, and run one set at a time as an evaluation.
+    # The dashboard's Scenarios page edits them entry by entry
+    # (ScenarioCatalogEntriesController) and previews an import before it
+    # is applied.
+    resources :scenario_catalogs, only: [ :index, :show, :create, :update, :destroy ] do
+      post :preview, on: :collection
+      member do
+        get :export
+        post :sync
+        post "sets/:set_id/run", action: :run_set, as: :run_set
+        post "sets/:set_id/materialize", action: :materialize_set, as: :materialize_set
+      end
+    end
+    scope "scenario_catalogs/:id", controller: "scenario_catalog_entries", as: :scenario_catalog do
+      post "products", action: :create_product, as: :products
+      patch "products/:product_id", action: :update_product, as: :product
+      delete "products/:product_id", action: :destroy_product
+      post "products/:product_id/sets", action: :create_set, as: :product_sets
+      patch "sets/:set_id", action: :update_set, as: :set
+      delete "sets/:set_id", action: :destroy_set
+      post "sets/:set_id/scenarios", action: :create_scenario, as: :set_scenarios
+      patch "sets/:set_id/scenarios/:scenario_id", action: :update_scenario, as: :set_scenario
+      delete "sets/:set_id/scenarios/:scenario_id", action: :destroy_scenario
+    end
+
     # Credentials: dashboard API keys (token shown once on create) and the
     # owner's own LLM provider credentials, both encrypted at rest.
     resources :api_keys, only: [ :index, :create, :destroy ]
@@ -172,6 +293,24 @@ ActionAgent::Engine.routes.draw do
       get :callback
     end
 
+    # The owner's GitHub App installations: install sends the admin to GitHub,
+    # which returns to callback; each installation's repositories are chosen
+    # with PATCH, and DELETE unlinks one (the App stays installed on GitHub).
+    resources :github_installations, only: [ :index, :update, :destroy ] do
+      collection do
+        get :install
+        get :callback
+      end
+      member do
+        get :repositories
+      end
+    end
+
+    # Creating the GitHub App from a manifest on a self-hosted dashboard.
+    resource :github_app_manifest, only: [ :create ] do
+      get :callback
+    end
+
     # Model catalogs for the agent builder (Ollama queried live from the
     # configured host; hosted providers curated).
     resources :provider_models, only: [ :index ]
@@ -181,6 +320,14 @@ ActionAgent::Engine.routes.draw do
     # against a plan answers through ActionAgent.usage_resolver, and a bare
     # mount reports unlimited rather than 404.
     resource :usage, only: [ :show ], controller: "usage"
+
+    # The Organization view's Team Members table. The host lists them
+    # through ActionAgent.members_resolver; without one it is the signed-in
+    # user alone.
+    resources :members, only: [ :index ]
+
+    # The owner's trace ingest key, read by the Organization view.
+    resource :telemetry_key, only: [ :show ], controller: "telemetry_keys"
   end
 
   # The account's agents presented as an authenticated MCP server (tools +
@@ -202,6 +349,10 @@ ActionAgent::Engine.routes.draw do
   match "mcp", to: "api/mcp#unsupported", via: [ :get, :delete ],
     constraints: ->(request) { request.delete? || !ActionAgent::Engine.html_request?(request) }
 
+  # The frame the session player runs in, holding the replay bundle and no
+  # data. See SessionPlayerController.
+  get "session_player", to: "session_player#show", as: :session_player
+
   # Everything else under the mount is a client-side route: render the
   # dashboard and let the browser resolve it. Anchored last so it can only
   # ever catch what the routes above did not, and refuses /api paths so a

data/lib/action_agent/claude_login_process.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+# A standalone PTY supervisor, deliberately without Rails, a logger, or a DB
+# connection. The one-use FIFO carries the pasted code only in kernel memory.
+# Files contain public flow state and the CLI's authorize URL, never output,
+# codes, credentials, or the PKCE verifier. A separate process lets requests
+# arrive at different web workers without losing the PTY.
+require "pty"
+require "io/console"
+require "json"
+require "fileutils"
+require "uri"
+
+directory, command, duration = ARGV
+directory = File.expand_path(directory)
+deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + Float(duration)
+status_path = File.join(directory, "status.json")
+fifo_path = File.join(directory, "code.pipe")
+write_status = lambda do |status, url = nil|
+  data = { status: status }
+  data[:authorize_url] = url if url
+  temporary = "#{status_path}.tmp"
+  File.write(temporary, JSON.generate(data), mode: "w", perm: 0o600)
+  File.rename(temporary, status_path)
+end
+
+reader = writer = pipe = nil
+pid = nil
+cancelled = false
+completed = false
+Signal.trap("TERM") { cancelled = true }
+Signal.trap("INT") { cancelled = true }
+
+begin
+  File.umask(0o077)
+  File.mkfifo(fifo_path, 0o600)
+  pipe = File.open(fifo_path, File::RDWR | File::NONBLOCK)
+  reader, writer, pid = PTY.spawn(command, "auth", "login", chdir: ENV.fetch("CLAUDE_CONFIG_DIR"))
+  reader.winsize = [ 40, 4096 ]
+  reader.echo = false
+  write_status.call("starting")
+  buffer = +""
+  submitted = false
+  loop do
+    break if cancelled
+    if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+      write_status.call("expired")
+      break
+    end
+    exited = Process.waitpid2(pid, Process::WNOHANG)
+    if exited
+      completed = exited.last.success?
+      write_status.call(exited.last.success? ? "completed" : "failed")
+      break
+    end
+    readable = IO.select([ reader, pipe ], nil, nil, 0.1)&.first || []
+    if readable.include?(pipe) && !submitted
+      code = pipe.read_nonblock(4096, exception: false)
+      if code.is_a?(String) && code.match?(/\A[^\s\x00-\x1f\x7f]{1,2048}\n\z/)
+        submitted = true
+        # No subsequent PTY output is parsed or retained. Even an echoing or
+        # failing CLI cannot leak this code through the public flow state.
+        buffer.clear
+        write_status.call("submitted")
+        writer.write(code)
+        writer.flush
+        code.clear
+      end
+    end
+    next unless readable.include?(reader)
+
+    begin
+      chunk = reader.read_nonblock(8192, exception: false)
+      next unless chunk.is_a?(String) && !submitted
+
+      buffer << chunk.force_encoding("UTF-8").scrub
+      buffer = buffer[-32_768..] || buffer
+      clean = buffer.gsub(/\e\[[0-9;?]*[A-Za-z]/, "")
+      url = clean[%r{https://(?:claude\.ai|platform\.claude\.com)/oauth/authorize\?[^\s\e]+}]
+      if url && URI.parse(url).query.to_s.include?("client_id=")
+        write_status.call("awaiting_code", url)
+      end
+    rescue Errno::EIO, EOFError
+      # A PTY reports EIO when the CLI exits. Reap it on the next iteration.
+    end
+  end
+  write_status.call("cancelled") if cancelled
+rescue StandardError
+  write_status.call("failed") rescue nil
+ensure
+  # PTY.spawn gives the CLI a session/process group of its own.
+  if pid
+    Process.kill("TERM", -pid) rescue nil
+    grace = Process.clock_gettime(Process::CLOCK_MONOTONIC) + 1
+    until (Process.waitpid(pid, Process::WNOHANG) rescue true)
+      break if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= grace
+      sleep 0.02
+    end
+    Process.kill("KILL", -pid) rescue nil
+    Process.waitpid(pid) rescue nil
+  end
+  [ reader, writer, pipe ].compact.each { |io| io.close rescue nil }
+  File.unlink(fifo_path) rescue nil
+  # A timed-out or interrupted login may have written a partial credential.
+  # Only a successfully completed CLI login may leave its config behind.
+  FileUtils.rm_rf(ENV.fetch("CLAUDE_CONFIG_DIR")) unless completed
+end

data/lib/action_agent/engine.rb

@@ -42,6 +42,12 @@ module ActionAgent
     config.action_agent = ActiveSupport::OrderedOptions.new
     config.app_middleware.insert_before Rails::Rack::Logger, ActionAgent::AssistantRequestFilter
 
+    # After, not in, an initializer: the host configures multi_tenant and
+    # permission_checker in its own initializers, which run after the engine's.
+    config.after_initialize do
+      ActionAgent.warn_about_unchecked_permissions
+    end
+
     # Whether a request is a browser asking for a page, as opposed to an API
     # or MCP client: the routes use it to tell the dashboard's client-side
     # deep links apart from protocol traffic on the same path.
@@ -55,11 +61,51 @@ module ActionAgent
     # directory to the host app's asset paths is what lets a plain
     # `mount ActionAgent::Engine` work without the host running a
     # JavaScript build — or having a JavaScript build at all.
-    # Provider credentials and API keys are posted to the dashboard in the
-    # clear and encrypted at rest — filtering keeps them out of the request
-    # logs in between, where the gem would otherwise print them verbatim.
+    # Provider credentials, API keys and answers to a run's requests for
+    # input (a secret among them) are posted to the dashboard in the clear
+    # and encrypted at rest — filtering keeps them out of the request logs
+    # in between, where the gem would otherwise print them verbatim.
+    # `answer` and `value` match whole names only, at any depth, so a host
+    # param or model attribute such as `values` or `default_value` is not
+    # filtered with them.
     initializer "action_agent.filter_parameters" do |app|
-      app.config.filter_parameters += [ :credential, :api_key, :access_token ]
+      # The last filters: RecordingEventIngest::BATCH_KEY, a batch that carries
+      # page content and console output, and an input request's answer. Each
+      # matches its key exactly, so a host parameter that merely contains those
+      # words is still logged. `answer` and `value` may also follow a dot:
+      # Rails 8.2 precompiles the host's filters into one expression and, once
+      # any of them names a nested key (Active Record Encryption adds
+      # `input_request.answer`), matches it against the dotted parameter path,
+      # where `\Aanswer\z` would no longer find `evaluation.answer`.
+      app.config.filter_parameters += [ :credential, :api_key, :access_token, :password, :claude_login_code, /\Arecording_events\z/, /(?:\A|\.)(?:answer|value)\z/i ]
+    end
+
+    # The project setup assistant's request_secret answers go to its
+    # handler. Registered on every reload, so the handler is always the
+    # current class's.
+    initializer "action_agent.secret_requests" do |app|
+      app.config.to_prepare do
+        ActionAgent::SecretRequests.register(ActionAgent::ProjectSetup::AGENT_CLASS_NAME, ActionAgent::ProjectSetup::SecretHandler.new)
+      end
+    end
+
+    # In a sandbox app (a checkout the dashboard booted, which bundles this
+    # engine), its backend sets ActionAgent::SandboxMail::DIRECTORY_ENV, and
+    # mail is written to files in that directory instead of being sent, so
+    # an agent exploring the app can read a sign-up's verification link.
+    # Registered as a load hook after the app's own configuration has been
+    # applied, so it wins over the environment file's delivery method. Set
+    # only in the sandbox's environment, it never reaches the checkout.
+    initializer "action_agent.sandbox_mail" do |app|
+      directory = ENV["ACTION_AGENT_SANDBOX_MAIL_DIR"].presence
+      next unless directory
+
+      location = File.expand_path(directory, app.root.to_s)
+      ActiveSupport.on_load(:action_mailer) do
+        self.delivery_method = :file
+        self.file_settings = { location: location }
+        self.perform_deliveries = true
+      end
     end
 
     # This engine's constants are spelled the way Zeitwerk's own inflector
@@ -207,8 +253,12 @@ module ActionAgent
       # i.e. the dashboard's only page 500s on every sprockets-rails host.
       # Propshaft serves everything on the load path and has no precompile
       # list, so the respond_to? check is what distinguishes them.
+      # action_agent_replay.js is the session player's own bundle, loaded
+      # only by SessionPlayerController's frame. action_agent_recorder.js is
+      # imported by the dashboard while the Run Agent workbench is open, from
+      # the URL the dashboard page names (DashboardController).
       if app.config.assets.respond_to?(:precompile)
-        app.config.assets.precompile |= %w[action_agent.js action_agent.css]
+        app.config.assets.precompile |= %w[action_agent.js action_agent.css action_agent_replay.js action_agent_recorder.js]
       end
     end
   end

data/lib/action_agent/secret_requests.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module ActionAgent
+  # The agents allowed to ask a person for a secret with the `request_secret`
+  # tool, each with the handler the answer is delivered to.
+  #
+  # Only agents the engine defines register here. The secret never reaches
+  # the model, so an agent may ask for one only when engine code is there to
+  # receive it. An agent is matched on its `agent_class_name`, which a
+  # dashboard user can also type, so a handler checks the run it is given is
+  # one it expects before keeping the value.
+  #
+  # A handler is a block, or an object with #call. An object may also
+  # answer these, each optional:
+  #
+  #   refusal(run:, name:)           why the run may not ask for +name+, or
+  #                                  nil; the model reads it as the call's
+  #                                  error and nobody is asked
+  #   prompt(run:, name:, prompt:)   the question a person reads, in place
+  #                                  of the model's +prompt+
+  #   answerable_by?(request, user)  whether +user+ may answer +request+, on
+  #                                  top of InputRequest#answerable_by?
+  #
+  # @example
+  #   ActionAgent::SecretRequests.register("ActionAgent::SetupAgent") do |run:, name:, value:|
+  #     ProjectSecret.store!(run:, name:, value:)
+  #   end
+  #
+  # @api private
+  module SecretRequests
+    @handlers = {}
+
+    class << self
+      # @param agent_class_name [String]
+      # @param handler [#call, nil] the handler, unless given as a block
+      # @yieldparam run [AgentRun] the run the answer belongs to
+      # @yieldparam name [String] the secret's name, as the model asked for it
+      # @yieldparam value [String] the answer
+      def register(agent_class_name, handler = nil, &block)
+        handler ||= block
+        raise ArgumentError, "A secret request handler needs a block or an object with #call" unless handler.respond_to?(:call)
+
+        @handlers[agent_class_name.to_s] = handler
+      end
+
+      def unregister(agent_class_name)
+        @handlers.delete(agent_class_name.to_s)
+      end
+
+      # @param agent [Agent, nil]
+      # @return [#call, nil]
+      def handler_for(agent)
+        name = agent&.agent_class_name.to_s
+        name.empty? ? nil : @handlers[name]
+      end
+
+      # Why +run+'s agent may not ask for +name+, or nil.
+      def refusal(agent, run:, name:)
+        handler = handler_for(agent)
+        handler.respond_to?(:refusal) ? handler.refusal(run: run, name: name) : nil
+      end
+
+      # The question a person is asked for +name+: the handler's wording, or
+      # the model's +prompt+.
+      def prompt(agent, run:, name:, prompt:)
+        handler = handler_for(agent)
+        handler.respond_to?(:prompt) ? handler.prompt(run: run, name: name, prompt: prompt) : prompt
+      end
+
+      # Whether +request+'s handler lets +user+ answer it. True for anything
+      # but a `secret` request whose agent's handler decides.
+      def answerable_by?(request, user)
+        return true unless request.kind == "secret"
+
+        handler = handler_for(request.subject.try(:agent))
+        handler.respond_to?(:answerable_by?) ? handler.answerable_by?(request, user) == true : true
+      end
+    end
+  end
+end

data/lib/action_agent/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ActionAgent
-  VERSION = "1.8.0"
+  VERSION = "1.9.0"
 end