rails_ai_admin 0.1.0

data/app/controllers/rails_ai_admin/application_controller.rb

@@ -0,0 +1,255 @@
+# frozen_string_literal: true
+
+module RailsAiAdmin
+  # Resolves fresh host authority for every request without altering host classes.
+  class ApplicationController < ActionController::Base
+    # Routing metadata is useful; arbitrary inputs and search text are not logs.
+    LOG_FILTER = /\A(?!(?:controller|action|resource|id|format)\z)/
+    protect_from_forgery with: :exception
+    wrap_parameters false
+    layout "rails_ai_admin/application"
+    helper RailsAiAdmin::FieldsHelper
+    helper RailsAiAdmin::NavigationHelper
+    helper RailsAiAdmin::FiltersHelper
+    helper RailsAiAdmin::ToolViewsHelper
+    helper RailsAiAdmin::HistoryHelper
+    helper RailsAiAdmin::DashboardHelper
+    prepend_before_action :secure_headers
+    before_action :authenticate_admin
+    after_action :notice_discarded_list_settings
+    helper_method :resource_navigation, :admin_csp_nonce, :list_page_path, :encoded_return_state, :navigation_state, :navigation_params, :list_return_path, :list_return_label, :return_state_discarded?, :return_navigation_fields, :list_state_fields, :visible_resources, :allowed_action?, :record_label, :collection_jobs_available?, :admin_associations, :assistant_available?, :searchable_resources, :audit_log_available?, :actor_labels, :assistant_for?
+
+    rescue_from AccessDenied, with: :deny_access
+    rescue_from ConfigurationError do
+      admin_status(:unavailable)
+    end
+    rescue_from ActionController::InvalidAuthenticityToken do
+      mark_form_recovery
+      admin_status(:invalid_request)
+    end
+
+    protected
+
+    # Layouts loading the prebuilt Turbo bundle need this nonce in csp-nonce meta.
+    def admin_csp_nonce
+      raise ConfigurationError, "Admin security headers have not been prepared" unless @admin_csp_nonce.is_a?(String) && @admin_csp_nonce.present?
+      String.new(@admin_csp_nonce).freeze
+    end
+
+    # Like Rails render, this does not halt an action. Callers must return when
+    # selecting a status instead of continuing toward business work.
+    def admin_status(kind)
+      @admin_status = Presentation::Status.fetch(kind)
+      response.headers.delete("X-RailsAiAdmin-Form-Recovery") if response.headers["X-RailsAiAdmin-Form-Recovery"] == "ready"
+      @status_sign_in_path = nil
+      if @admin_status.kind == "authentication_required"
+        path = RailsAiAdmin.configuration.authentication_path
+        @status_sign_in_path = String.new(path).freeze if path.is_a?(String) && path.valid_encoding? && path.ascii_only? && path.match?(Configuration::INTERNAL_PATH)
+      end
+      if request.format.html? || request.format.turbo_stream?
+        begin
+          render template: "rails_ai_admin/statuses/show", layout: "rails_ai_admin/status", formats: [ :html ],
+            content_type: "text/html", status: @admin_status.http_status
+        rescue StandardError
+          self.response_body = nil
+          render plain: @admin_status.message, content_type: "text/plain", status: @admin_status.http_status
+        end
+      else
+        render plain: @admin_status.message, status: @admin_status.http_status
+      end
+    end
+
+    private
+
+    def process_action(*)
+      filters = Array(request.get_header("action_dispatch.parameter_filter")) + [ LOG_FILTER ]
+      request.set_header("action_dispatch.parameter_filter", filters)
+      super
+    end
+
+    def secure_headers
+      @admin_csp_nonce = SecureRandom.base64(24)
+      response.headers["Cache-Control"] = "no-store, private"
+      response.headers["Content-Security-Policy"] = "default-src 'self'; script-src 'self'; style-src 'self' 'nonce-#{@admin_csp_nonce}'; img-src 'self' data:; connect-src 'self'; base-uri 'self'; form-action 'self'; frame-ancestors 'none'; object-src 'none'"
+      response.headers["X-Content-Type-Options"] = "nosniff"
+      response.headers["Referrer-Policy"] = "same-origin"
+    end
+
+    def authenticate_admin
+      name = RailsAiAdmin.configuration.context_adapter
+      @context = name&.constantize&.new&.resolve(self)
+      raise AccessDenied, "UNAUTHENTICATED" unless @context.is_a?(Context)
+    end
+
+    def deny_access(error)
+      status = Presentation::Status.for_code(error.code)
+      if status.kind == "authentication_required" && (target = sign_in_redirect)
+        return redirect_to(target, status: :see_other)
+      end
+      mark_form_recovery if status.kind == "authentication_required"
+      admin_status(status.kind)
+    end
+
+    # A plain page visit by a signed-out person goes to the host's sign-in
+    # page with the requested path (RAA-024). Form submissions, recovery,
+    # frames and non-HTML requests keep the 401, so no open form is lost. The
+    # query string is left out: it can carry search text. The host must still
+    # validate return_to before redirecting to it.
+    def sign_in_redirect
+      path = RailsAiAdmin.configuration.authentication_path
+      return unless path.is_a?(String) && path.match?(Configuration::INTERNAL_PATH)
+      return unless request.get? && request.format.html? && !request.xhr?
+      return if request.headers["Turbo-Frame"] || request.headers["X-RailsAiAdmin-Recovery-Intent"]
+      requested = request.path
+      return path unless requested.is_a?(String) && requested.match?(%r{\A/(?![/\\])[^\s]*\z}) && requested.length <= 2000
+      "#{path}?#{{ return_to: requested }.to_query}"
+    end
+
+    def mark_form_recovery
+      if is_a?(ResourcesController) && %w[create update].include?(action_name)
+        response.headers["X-RailsAiAdmin-Form-Recovery"] = "session"
+      end
+    end
+
+    def resolve_list_navigation
+      raw = params[:return_to]
+      raw = raw.to_unsafe_h if raw.is_a?(ActionController::Parameters)
+      access = Authorization::Access.new(@context, @resource)
+      @list_navigation = if action_name == "recover_form"
+        Navigation::ListState.from_header(access, request.headers["X-RailsAiAdmin-Return-State"])
+      else
+        Navigation::ListState.new(access, raw)
+      end
+    end
+
+    def encoded_return_state = @list_navigation&.encoded || ""
+    def navigation_state = @list_navigation&.state || {}
+    def navigation_params = navigation_state.empty? ? {} : { return_to: navigation_state }
+    def return_state_discarded? = @list_navigation&.discarded? == true
+
+    def list_return_path
+      @list_navigation&.index_allowed? ? resources_path(resource: @resource.key, **navigation_state.symbolize_keys) : root_path
+    end
+
+    def list_page_path(page)
+      raise ConfigurationError, "Invalid list page" unless page.is_a?(Integer) && (1..1000).cover?(page)
+      state = page == 1 ? navigation_state.except("page") : navigation_state.merge("page" => page.to_s)
+      resources_path(resource: @resource.key, **state.symbolize_keys)
+    end
+
+    def list_return_label = @list_navigation&.index_allowed? ? @resource.label : t("rails_ai_admin.layout.administration")
+
+    def return_navigation_fields
+      helpers.safe_join(Navigation::ListState.form_pairs(navigation_state, "return_to").map { |name, value| helpers.hidden_field_tag(name, value, id: nil) })
+    end
+
+    # Hidden inputs that keep selected list settings in another GET list form.
+    def list_state_fields(*keys)
+      helpers.safe_join(Navigation::ListState.form_pairs(navigation_state.slice(*keys)).map { |name, value| helpers.hidden_field_tag(name, value, id: nil) })
+    end
+
+    def notice_discarded_list_settings
+      return unless response.redirect? && return_state_discarded?
+      message = t("rails_ai_admin.layout.settings_unavailable")
+      flash[:notice] = [ flash[:notice], message ].compact.join(" ") unless flash[:notice].to_s.include?(message)
+    end
+
+    # Request-only memoization; no menu/grant snapshot survives authentication.
+    def resource_navigation
+      @resource_navigation ||= Navigation::Menu.build(context: @context,
+        resources: RailsAiAdmin.registry.resources, current_key: @resource&.key)
+    end
+
+    def visible_resources
+      RailsAiAdmin.registry.resources.select do |resource|
+        Authorization::Access.new(@context, resource).authorize!(:index)
+      rescue AccessDenied
+        false
+      end
+    end
+
+    # Resources in the menu that this actor may list and search, for the
+    # header search box. Request-local; no grant survives the request.
+    def searchable_resources
+      @searchable_resources ||= RailsAiAdmin.registry.resources.select do |resource|
+        next false if resource.navigation.hidden
+        access = Authorization::Access.new(@context, resource)
+        access.authorize!(:index)
+        access.fields(:search).any?
+      rescue AccessDenied
+        false
+      end
+    end
+
+    def allowed_action?(resource, action, record = nil)
+      Authorization::Access.new(@context, resource).authorize!(action, record)
+    rescue AccessDenied
+      false
+    end
+
+    # Whether this page may offer "Ask the assistant" for a resource.
+    def assistant_for?(resource)
+      return false unless assistant_available?
+      Authorization::Access.new(@context, resource).authorize_assistant!
+    rescue AccessDenied
+      false
+    end
+
+    def audit_log_available?
+      return @audit_log_available unless @audit_log_available.nil?
+      @audit_log_available = RailsAiAdmin.registry.resources.any? do |resource|
+        Authorization::Access.new(@context, resource).authorize_audit_log!
+      rescue AccessDenied
+        false
+      end
+    end
+
+    def collection_jobs_available?
+      RailsAiAdmin.registry.resources.any? do |resource|
+        RailsAiAdmin.operation_registry.custom(resource).any? do |definition|
+          next false unless definition.scope == :collection
+          Authorization::Access.new(@context, resource).authorize_receipt!(definition.key, nil)
+        rescue AccessDenied
+          false
+        end
+      end
+    end
+
+    # The menu link follows the same grant as the assistant pages.
+    def assistant_available?
+      return false unless RailsAiAdmin.configuration.assistant
+      require "rails_ai_admin/assistant"
+      @assistant_available = Assistant.available?(@context) if @assistant_available.nil?
+      @assistant_available
+    end
+
+    # Request-local reference cache. Each target is read through its own
+    # resource policy; nothing is shared across requests or actors.
+    def admin_associations
+      @admin_associations ||= Fields::Association.new(@context, @resource)
+    end
+
+    # Display names for stored actor references. The context adapter may
+    # answer actor_labels(context:, actor_refs:) with a Hash; otherwise a
+    # reference reads as "User #42".
+    def actor_labels(refs)
+      adapter = RailsAiAdmin.configuration.context_adapter&.constantize&.new
+      given = adapter.respond_to?(:actor_labels) ? adapter.actor_labels(context: @context, actor_refs: refs) : {}
+      given = {} unless given.is_a?(Hash)
+      refs.to_h do |ref|
+        label = given[ref]
+        label = nil unless label.is_a?(String) && label.valid_encoding? && label.length.between?(1, 200)
+        [ ref, label || default_actor_label(ref) ]
+      end
+    end
+
+    def default_actor_label(ref)
+      _, _, kind, id = ref.to_s.split(":", 4)
+      kind && id ? "#{kind.demodulize.titleize} ##{id}" : ref.to_s
+    end
+
+    def record_label(resource, record, values: nil, view: :show)
+      Authorization::Access.new(@context, resource).record_label(record, values: values, view: view)
+    end
+  end
+end

data/app/controllers/rails_ai_admin/assistant_controller.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+module RailsAiAdmin
+  # Admin Chat pages. A request only saves a message as an inbox turn and
+  # enqueues work; no provider call runs in a web request. RubyLLM is loaded
+  # inside actions only, so conventional hosts can eager-load this file.
+  class AssistantController < ApplicationController
+    RETRYABLE = %w[PROVIDER_UNAVAILABLE ASSISTANT_FAILED ATTEMPTS_EXHAUSTED AI_UNAVAILABLE STEP_LIMIT].freeze
+    FAILURES = {
+      "AI_UNAVAILABLE" => "The assistant is not available right now. The rest of the administration works as usual.",
+      "AI_REJECTED" => "The AI provider rejected this request. Try a shorter or different message.",
+      "PROVIDER_UNAVAILABLE" => "The AI provider did not respond. Your message is saved; try again.",
+      "ASSISTANT_FAILED" => "The assistant could not finish. Your message is saved; try again.",
+      "ATTEMPTS_EXHAUSTED" => "The assistant stopped after several attempts. Your message is saved; try again.",
+      "STEP_LIMIT" => "The assistant stopped before finishing this request. Try a narrower question.",
+      "AUTHORIZATION_REVOKED" => "Your access changed, so this request was not answered.",
+      "NOT_ALLOWED" => "No resources are available to the assistant for your account.",
+      "CANCELLED" => "Stopped."
+    }.freeze
+
+    before_action :require_assistant
+    before_action :load_chat, except: %i[index create]
+    around_action :bind_surface_context
+
+    def index
+      @chats = Assistant::Chat.for_owner(@context).order(updated_at: :desc, id: :desc).limit(50).to_a
+    end
+
+    # A new chat; from a record or list page it starts with the question and a
+    # server-written "Context:" line naming that page.
+    def create
+      question = params[:content]
+      raise AccessDenied, "INVALID_QUERY" unless question.nil? || question.is_a?(String)
+      chat = Assistant.create_chat!(@context)
+      if question.present?
+        content = [ page_context_line, question.strip ].compact.join("\n\n").first(Assistant::Coordinator::MAX_CONTENT)
+        Assistant::Coordinator.admit!(chat, kind: "message", content: content, admission_key: "message:#{SecureRandom.uuid}")
+      end
+      redirect_to assistant_conversation_path(chat_ref: chat.ref), status: :see_other
+    rescue ::RubyLLM::ModelNotFoundError, ::RubyLLM::ModelRegistryError
+      admin_status(:unavailable)
+    end
+
+    def show
+      prepare_transcript
+      if turbo_frame_request?
+        # A complete standards-mode document; Turbo extracts the matching frame.
+        render :frame, layout: "rails_ai_admin/frame"
+      else
+        @admission_key = "message:#{SecureRandom.uuid}"
+      end
+    end
+
+    def message
+      return admin_status(:conflict) unless @chat.current_for?(@context)
+      Assistant::Coordinator.admit!(@chat, kind: "message", content: params[:content], admission_key: params[:admission_key])
+      redirect_to assistant_conversation_path(chat_ref: @chat.ref), status: :see_other
+    rescue AccessDenied => error
+      raise unless %w[INVALID_QUERY RATE_LIMITED].include?(error.code)
+      prepare_transcript
+      @admission_key = params[:admission_key].is_a?(String) && params[:admission_key].match?(Assistant::Coordinator::ADMISSION_KEY) ? params[:admission_key] : "message:#{SecureRandom.uuid}"
+      @draft = params[:content].is_a?(String) ? params[:content].first(Assistant::Coordinator::MAX_CONTENT + 1) : ""
+      if error.code == "RATE_LIMITED"
+        @message_error = t("rails_ai_admin.assistant.rate_limited", count: RailsAiAdmin.configuration.assistant_daily_message_limit)
+        return render :show, status: :too_many_requests
+      end
+      @message_error = t("rails_ai_admin.assistant.invalid_message", count: Assistant::Coordinator::MAX_CONTENT)
+      render :show, status: :unprocessable_content
+    end
+
+    # Stops waiting turns now and asks a running one to stop at its next
+    # checkpoint. Committed business results are never undone.
+    def cancel
+      Assistant::Turn.transaction do
+        Assistant::Chat.lock.find(@chat.id)
+        @chat.turns.where(status: "queued").update_all(status: "cancelled", error_code: "CANCELLED", completed_at: Time.current, updated_at: Time.current)
+        @chat.cancel if @chat.turns.where(status: "running").exists?
+      end
+      redirect_to assistant_conversation_path(chat_ref: @chat.ref), status: :see_other
+    end
+
+    # Requeues the latest failed turn. The saved human message is reused, so
+    # retrying never repeats it in the conversation.
+    def retry_turn
+      return admin_status(:conflict) unless @chat.current_for?(@context)
+      Assistant::Turn.transaction do
+        Assistant::Chat.lock.find(@chat.id)
+        turn = @chat.turns.reorder(sequence: :desc).first
+        raise AccessDenied, "CONFLICT" unless turn&.status == "failed" && RETRYABLE.include?(turn.error_code)
+        turn.update!(status: "queued", attempts: 0, error_code: nil, next_attempt_at: nil, completed_at: nil)
+      end
+      Assistant::Coordinator.enqueue_after_commit(@chat.ref)
+      redirect_to assistant_conversation_path(chat_ref: @chat.ref), status: :see_other
+    end
+
+    def archive
+      @chat.update!(status: "archived")
+      redirect_to assistant_path, status: :see_other, notice: t("rails_ai_admin.assistant.archived")
+    end
+
+    private
+
+    # Names the page only when the actor may show it to the assistant now. The
+    # line is data for the model and grants nothing; tools check again.
+    def page_context_line
+      about = params[:about]
+      return unless about.is_a?(ActionController::Parameters)
+      resource = RailsAiAdmin.registry.fetch(about[:resource].to_s)
+      access = Authorization::Access.new(@context, resource)
+      access.authorize_assistant!
+      id = about[:id]
+      if id.is_a?(String) && id.present?
+        raise AccessDenied unless access.canonical_id?(id)
+        record = access.find!(id)
+        "Context: I am looking at #{resource.label.singularize} #{record.id} (\"#{access.record_label(record).truncate(120)}\") in the #{resource.key} resource."
+      else
+        query = about[:q].is_a?(String) ? about[:q].strip.first(100) : nil
+        scope = about[:scope].is_a?(String) ? access.named_scopes.find { |definition| definition.name.to_s == about[:scope] } : nil
+        details = [ (query.present? ? "searching for \"#{query}\"" : nil), (scope ? "on the #{scope.label} tab (scope #{scope.name})" : nil) ].compact
+        "Context: I am looking at the #{resource.label} list (the #{resource.key} resource)#{details.any? ? ", #{details.join(', ')}" : ''}."
+      end
+    rescue AccessDenied, ConfigurationError, KeyError
+      nil
+    end
+
+    def require_assistant
+      raise AccessDenied unless RailsAiAdmin.configuration.assistant
+      require "rails_ai_admin/assistant"
+      raise AccessDenied unless Assistant.available?(@context)
+    end
+
+    def load_chat
+      @chat = Assistant::Chat.owned(@context, params[:chat_ref]) || raise(AccessDenied)
+    end
+
+    # Surfaces in a conversation render through the admin-bound context.
+    def bind_surface_context(&block)
+      return yield unless RailsAiAdmin.configuration.surfaces
+      require "rails_ai_admin/integrations/tool_views"
+      Integrations::ToolViews.ensure_registered!
+      Integrations::ToolViews.with_context(@context, &block)
+    end
+
+    # A security change closes the chat: its transcript, including old tool
+    # output, is no longer shown under the new authority.
+    def prepare_transcript
+      @current = @chat.current_for?(@context)
+      @entries = @current ? Assistant::Transcript.new(@context, @chat).entries : []
+      last = @chat.turns.reorder(sequence: :desc).first
+      @pending = @current && @chat.turns.where(status: Assistant::Turn::ACTIVE).exists?
+      running = @pending ? @chat.turns.where(status: "running").reorder(:sequence).first : nil
+      @running = !running.nil?
+      # The reply being written, shown only under the chat's current authority.
+      @streaming_text = running&.draft.presence
+      retrying = @pending && @chat.turns.where(status: "queued").where.not(error_code: nil).reorder(:sequence).first
+      @retry_status = t("rails_ai_admin.assistant.retrying", attempt: retrying.attempts + 1, attempts: Assistant::Coordinator::MAX_ATTEMPTS) if retrying
+      @failure = last if last&.status == "failed" || last&.status == "cancelled"
+      code = @failure && (FAILURES.key?(@failure.error_code.to_s) ? @failure.error_code.to_s : "ASSISTANT_FAILED")
+      @failure_message = code && t(code.downcase, scope: %i[rails_ai_admin assistant failures], default: FAILURES.fetch(code))
+      @retryable = @current && @failure&.status == "failed" && RETRYABLE.include?(@failure.error_code)
+      @surface_scope = Integrations::ToolViews.scope_for(@context) if RailsAiAdmin.configuration.surfaces
+    end
+  end
+end

data/app/controllers/rails_ai_admin/audit_controller.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module RailsAiAdmin
+  # Recent changes across records for the resources the actor may audit.
+  class AuditController < ApplicationController
+    FILTERS = %w[resource operation status actor before].freeze
+
+    def index
+      @log = Presentation::AuditLog.new(@context)
+      @filters = FILTERS.to_h { |key| [ key, params[key] ] }.compact_blank
+      raise AccessDenied, "INVALID_QUERY" unless @filters.values.all? { |value| value.is_a?(String) }
+      @page = @log.page(**@filters.transform_keys(&:to_sym))
+      @actor_labels = actor_labels(@page.entries.map(&:actor_ref).uniq | [ @filters["actor"] ].compact)
+    end
+  end
+end

data/app/controllers/rails_ai_admin/collection_jobs_controller.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module RailsAiAdmin
+  class CollectionJobsController < ApplicationController
+    # The page exists only where its menu link does (RAA-030).
+    def index
+      raise AccessDenied unless collection_jobs_available?
+      @jobs = Collections::Queries.new.recent(context: @context)
+    end
+
+    def show
+      @job = Collections::Queries.new.fetch(context: @context, job_ref: params[:job_ref])
+      @resource = RailsAiAdmin.registry.fetch(@job.resource_key)
+      resolve_list_navigation
+    end
+
+    def cancel
+      run = OperationRun.find_by(id: params[:job_ref], actor_ref: @context.actor_ref, tenant_ref: @context.tenant_ref)
+      raise AccessDenied unless run
+      @resource = RailsAiAdmin.registry.fetch(run.resource_key)
+      resolve_list_navigation
+      result = Collections::Runner.new.cancel(context: @context, job_ref: params[:job_ref])
+      return render plain: t("rails_ai_admin.collection_jobs.busy"), status: :conflict if result.code == "CONFLICT"
+      if result.code == "OUTCOME_UNKNOWN"
+        return redirect_to collection_job_path(job_ref: result.job_ref, **navigation_params), status: :see_other,
+          notice: t("rails_ai_admin.collection_jobs.cancel_unknown")
+      end
+      raise AccessDenied unless result.job_ref
+      redirect_to collection_job_path(job_ref: result.job_ref, **navigation_params), status: :see_other,
+        notice: t("rails_ai_admin.collection_jobs.cancelled")
+    end
+  end
+end

data/app/controllers/rails_ai_admin/collection_operations_controller.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module RailsAiAdmin
+  class CollectionOperationsController < ApplicationController
+    before_action :resolve_operation
+
+    def new
+      load_form
+      @form_values, @errors = {}, {}
+    end
+
+    def preflight
+      input = submitted_input
+      @proposal = Collections::Runner.new.preflight(context: @context, resource: @resource, operation: @definition.key,
+        selection_ref: params[:selection_ref], input: input)
+      if @proposal.is_a?(Collections::Result)
+        render_rejection(@proposal, input)
+      else
+        @wire_input = @proposal.intent.input_payload.to_json
+        render :confirmation
+      end
+    end
+
+    def execute
+      input = confirmed_input
+      result = Collections::Runner.new.admit(context: @context, intent_ref: params[:intent_ref], input: input,
+        human_confirmed: true, binding: { resource_key: @resource.key, operation: @definition.key, selection_id: params[:selection_ref] })
+      if result.accepted?
+        redirect_to collection_job_path(job_ref: result.job_ref, **navigation_params), status: :see_other, notice: t("rails_ai_admin.collection_operations.admitted")
+      else
+        render_rejection(result, input)
+      end
+    end
+
+    private
+
+    def resolve_operation
+      @resource = RailsAiAdmin.registry.fetch(params[:resource])
+      @definition = RailsAiAdmin.operation_registry.fetch(@resource, params[:operation])
+      raise AccessDenied unless @definition.custom? && @definition.scope == :collection
+      @access = Authorization::Access.new(@context, @resource)
+      resolve_list_navigation
+    end
+
+    def load_form
+      @selection = Selections::Builder.new.revalidate(context: @context, selection_ref: params[:selection_ref], resource: @resource)
+      @access.authorize!(@definition.key)
+      @form_fields = @definition.fields(@access, nil)
+    end
+
+    def submitted_input
+      value = params[:input]
+      raise AccessDenied, "INVALID_QUERY" unless value.nil? || value.is_a?(ActionController::Parameters)
+      value ? value.to_unsafe_h : {}
+    end
+
+    def confirmed_input
+      value = params[:confirmed_input]
+      raise AccessDenied, "INVALID_QUERY" unless value.is_a?(String) && value.bytesize <= 16_384
+      JSON.parse(value)
+    rescue JSON::ParserError
+      raise AccessDenied, "INVALID_QUERY"
+    end
+
+    def render_rejection(result, input)
+      raise AccessDenied if result.code == "NOT_FOUND"
+      @failure_code = result.code
+      @uncertain_job_ref = result.job_ref if result.code == "OUTCOME_UNKNOWN"
+      if result.code == "VALIDATION_FAILED"
+        load_form
+        @form_values = input.is_a?(Hash) ? input.stringify_keys.slice(*@form_fields.map { |field| field.name.to_s }).reject { |_, value| value.is_a?(Array) || value.is_a?(Hash) } : {}
+        @errors = result.errors
+        render :new, status: :unprocessable_content
+      else
+        render :failure, status: %w[TIMEOUT OPERATION_FAILED].include?(result.code) ? :service_unavailable : :conflict
+      end
+    end
+  end
+end

data/app/controllers/rails_ai_admin/custom_controller.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module RailsAiAdmin
+  # Public base for host-owned Rails routes, controllers and partials. Hosts keep
+  # their own route helpers/layout; admin engine links use the mounted proxy.
+  class CustomController < ApplicationController
+    layout false
+    helper_method :admin_routes
+
+    protected
+
+    def admin_context
+      raise AccessDenied, "UNAUTHENTICATED" unless @context.is_a?(Context)
+      @context
+    end
+
+    # Resolving an access object grants nothing: explicitly authorize, use its
+    # scoped find/relation and project permitted values before displaying them.
+    def admin_access(resource_key)
+      Authorization::Access.new(admin_context, RailsAiAdmin.registry.fetch(resource_key))
+    end
+
+    def admin_operation_runner = Operations::Runner.new
+    def admin_routes = rails_ai_admin
+  end
+end

data/app/controllers/rails_ai_admin/dashboard_controller.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module RailsAiAdmin
+  class DashboardController < ApplicationController # :nodoc:
+    # Counts appear only for resources whose list already opts into exact
+    # counts, with the same bound (10,000) and default list tab.
+    def index
+      @widgets = Presentation::Dashboard.build(@context, RailsAiAdmin.registry.resources.reject { |resource| resource.navigation.hidden })
+      @counts = RailsAiAdmin.registry.resources.each_with_object({}) do |resource, counts|
+        next unless resource.index.count == :exact
+        counts[resource.key.to_s] = Queries::List.new(@context, resource).count
+      rescue AccessDenied
+        next
+      end
+    end
+  end
+end

data/app/controllers/rails_ai_admin/exports_controller.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module RailsAiAdmin
+  # Downloads the current list as CSV. POST keeps GET requests free of the
+  # audit write and lets the CSRF token guard the download.
+  class ExportsController < ApplicationController
+    def create
+      @resource = RailsAiAdmin.registry.fetch(params[:resource])
+      access = Authorization::Access.new(@context, @resource)
+      access.authorize_export!
+      raw = params.to_unsafe_h.slice(*Navigation::ListState::KEYS).except("page")
+      @list_navigation = Navigation::ListState.new(access, raw, strict: true)
+      raise AccessDenied, "INVALID_QUERY" if @list_navigation.discarded?
+      state = @list_navigation.state
+      result = Presentation::CsvExport.new(@context, @resource).call(search: state["q"], sort: state["sort"],
+        direction: state.fetch("direction", "asc"), scope: state["scope"], filters: state["filter"])
+      if result.too_many
+        redirect_to resources_path(resource: @resource.key, **state.symbolize_keys), status: :see_other,
+          notice: t("rails_ai_admin.exports.too_many", limit: RailsAiAdmin.configuration.export_limit)
+        return
+      end
+      AuditEvent.create!(actor_ref: @context.actor_ref, tenant_ref: @context.tenant_ref, resource_key: @resource.key.to_s,
+        operation: "export", status: "succeeded", code: "OK", correlation_ref: SecureRandom.uuid, origin: "ui",
+        changed_fields: result.fields, created_at: Time.current)
+      filename = "#{@resource.key}-#{Time.current.in_time_zone(@context.time_zone).strftime('%Y%m%d-%H%M')}.csv"
+      send_data result.body, filename: filename, type: "text/csv; charset=utf-8", disposition: "attachment"
+    end
+  end
+end

data/app/controllers/rails_ai_admin/files_controller.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module RailsAiAdmin
+  # Serves an attached file after the same checks as the record's page: the
+  # record in scope, its show grant and a current read grant for the field.
+  # Only raster images are shown inline; everything else downloads.
+  class FilesController < ApplicationController
+    def show
+      raise AccessDenied unless defined?(::ActiveStorage::Blob)
+      resource = RailsAiAdmin.registry.fetch(params[:resource])
+      access = Authorization::Access.new(@context, resource)
+      raise AccessDenied unless access.canonical_id?(params[:id])
+      record = access.find!(params[:id])
+      field = access.fields(:read, record).find { |candidate| Field::FILE_TYPES.include?(candidate.scalar_type) && candidate.name.to_s == params[:field] }
+      raise AccessDenied unless field
+      attached = access.attachment(record, field)
+      blob = if field.scalar_type == :files
+        id = params[:attachment]
+        raise AccessDenied unless id.is_a?(String) && id.match?(Field::REFERENCE)
+        access.stored_attachments(record, field).find_by(id: id)&.blob
+      else
+        attached.attached? ? attached.blob : nil
+      end
+      raise AccessDenied unless blob
+      inline = params[:disposition] == "inline" && Fields::INLINE_IMAGE_TYPES.include?(blob.content_type)
+      # A served file is a document of its own: no script, no framing.
+      response.headers["Content-Security-Policy"] = "default-src 'none'; img-src 'self'; style-src 'unsafe-inline'; sandbox"
+      response.headers["Cache-Control"] = "no-store, private"
+      response.headers["Content-Type"] = inline ? blob.content_type : "application/octet-stream"
+      response.headers["Content-Disposition"] = ActionDispatch::Http::ContentDisposition.format(
+        disposition: inline ? "inline" : "attachment", filename: blob.filename.sanitized)
+      response.headers["Content-Length"] = blob.byte_size.to_s
+      # Streamed in the service's chunks; a large file is never held in memory.
+      self.response_body = Enumerator.new { |body| blob.download { |chunk| body << chunk } }
+    end
+  end
+end