rails_ai_admin 0.1.0

data/lib/rails_ai_admin/input_schema.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require "json"
+require "digest"
+require "openssl"
+require "securerandom"
+
+module RailsAiAdmin
+  # Compiles explicitly declared fields into typed inputs and canonical digests.
+  class InputSchema
+    Coercion = Data.define(:values, :errors) do
+      def valid? = errors.empty?
+    end
+
+    def initialize(fields, partial: false)
+      raise ConfigurationError, "Computed fields cannot be input fields" if fields.any?(&:virtual?)
+      @fields = fields.index_by { |field| field.name.to_s }
+      @partial = partial
+    end
+
+    def coerce(input, time_zone: "UTC")
+      return Coercion.new({}, { "base" => [ Field.error_message(:not_object, "must be an object") ] }) unless input.is_a?(Hash)
+      values, errors = {}, {}
+      input = input.stringify_keys
+      errors["base"] = [ Field.error_message(:undeclared_fields, "contains undeclared fields") ] if (input.keys - @fields.keys).any?
+      @fields.each do |name, field|
+        # An empty password box means "keep the current password".
+        input_value = input[name]
+        if !input.key?(name) || field.scalar_type == :password && input_value.is_a?(String) && input_value.match?(Field::BLANK)
+          errors[name] = [ Field.error_message(:required, "is required") ] if !@partial && field.options[:required]
+          next
+        end
+        begin
+          values[name] = field.coerce(input[name], time_zone: time_zone)
+        rescue ArgumentError => error
+          errors[name] = [ error.message ]
+        end
+      end
+      Coercion.new(values.freeze, errors.freeze)
+    end
+
+    def json_schema
+      required = @partial ? [] : @fields.values.select { |field| field.options[:required] }.map { |field| field.name.to_s }
+      { "type" => "object", "properties" => @fields.transform_values(&:json_schema), "required" => required, "additionalProperties" => false }
+    end
+
+    # Serializes semantic values independently of hash insertion order.
+    def self.digest(input)
+      Digest::SHA256.hexdigest(JSON.generate(canonical(input)))
+    end
+
+    # Keyed so a stored digest is not an unsalted hash of a password. Hosts
+    # derive it from secret_key_base; without an application (plain library
+    # tests) it is random per process.
+    def self.secret_key
+      @secret_key ||= if defined?(Rails) && Rails.respond_to?(:application) && Rails.application&.respond_to?(:key_generator) && Rails.application.secret_key_base.present?
+        Rails.application.key_generator.generate_key("rails_ai_admin/input_digest", 32)
+      else
+        SecureRandom.bytes(32)
+      end
+    end
+
+    def self.canonical(value)
+      case value
+      when Hash then value.stringify_keys.sort.to_h.transform_values { |entry| canonical(entry) }
+      when Array then value.map { |entry| canonical(entry) }
+      when BigDecimal then { "$decimal" => value.to_s("F") }
+      when Time, ActiveSupport::TimeWithZone then { "$time" => value.utc.iso8601(6) }
+      when Date then { "$date" => value.iso8601 }
+      when Fields::FileValue, Fields::RejectedUpload then value.to_h.transform_keys(&:to_s)
+      when Field::Secret then { "$secret" => OpenSSL::HMAC.hexdigest("SHA256", secret_key, value) }
+      else value
+      end
+    end
+  end
+end

data/lib/rails_ai_admin/integrations/propose_operation.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/digest/uuid"
+require "ruby_llm"
+require "rails_ai_admin/integrations/tool_views"
+
+module RailsAiAdmin
+  module Integrations
+    # A RubyLLM tool that lets an assistant propose an opted-in member operation.
+    #
+    # The model chooses a resource, record, operation and input; all of it is
+    # untrusted. The server re-runs the normal preflight under the current admin
+    # Context (policy scope, action and input grants, typed coercion) and then
+    # presents the review Surface. The tool cannot confirm or execute anything:
+    # only the human's own Surface submission does, through the shared Runner.
+    #
+    # Each provider tool call maps to one deterministic intent and one Surface,
+    # so a replayed call (for example after a crash before its result was saved)
+    # never creates a second approval request.
+    class ProposeOperation < ::RubyLLM::Tool
+      NAMESPACE = "9b2f2f41-2a4e-4d7b-9bde-8f3f6a1d0c55"
+      CONVERSATION = /\Araa:conversation:[A-Za-z0-9_-]{1,100}\z/
+      RECORD_REF = /\A[A-Za-z0-9_-]{1,64}\z/
+
+      def self.tool_name = "raa_propose_operation"
+
+      description "Propose an admin operation on one record. Nothing changes until the signed-in user reviews and confirms it in the interactive review this presents. Never tell the user the operation is done."
+
+      attr_reader :catalog
+
+      # context: the authenticated admin Context; conversation: a server-owned
+      # "raa:conversation:<id>" reference. Neither may come from model output.
+      def initialize(context:, conversation:)
+        raise AccessDenied, "UNAUTHENTICATED" unless context.is_a?(Context)
+        unless conversation.is_a?(String) && conversation.match?(CONVERSATION)
+          raise ConfigurationError, "conversation must be a raa:conversation reference"
+        end
+        raise ConfigurationError, "Assistant proposals require config.surfaces" unless RailsAiAdmin.configuration.surfaces
+        @context, @conversation = context, conversation.dup.freeze
+        @catalog = build_catalog.freeze
+        super()
+      end
+
+      def description
+        operations = @catalog.map do |entry|
+          fields = entry[:definition].handler_class.input.map do |field|
+            values = field.choice_values.any? ? " (#{field.choice_values.join('|')})" : ""
+            "#{field.name}: #{field.scalar_type}#{values}#{field.options[:required] ? ', required' : ''}"
+          end
+          "#{entry[:resource].key}.#{entry[:definition].key} — #{entry[:definition].description}; input #{fields.join('; ')}"
+        end
+        "#{self.class.description} Available: #{operations.join(' | ')}"
+      end
+
+      def parameters_schema
+        {
+          "type" => "object", "additionalProperties" => false, "required" => %w[resource record operation input],
+          "properties" => {
+            "resource" => { "type" => "string", "enum" => @catalog.map { |entry| entry[:resource].key.to_s }.uniq },
+            "record" => { "type" => "string", "maxLength" => 64, "description" => "The record id shown in the admin" },
+            "operation" => { "type" => "string", "enum" => @catalog.map { |entry| entry[:definition].key.to_s }.uniq },
+            "input" => { "type" => "object", "description" => "Operation input fields by name" }
+          }
+        }
+      end
+
+      def execute(resource:, record:, operation:, input:, tool_call: nil)
+        raise AccessDenied, "INVALID_TOOL_CALL" unless tool_call.is_a?(::RubyLLM::ToolCall) && tool_call.name == name && tool_call.id.is_a?(String) && tool_call.id.bytesize.between?(1, 150)
+        entry = @catalog.find { |item| item[:resource].key.to_s == resource.to_s && item[:definition].key.to_s == operation.to_s }
+        raise AccessDenied unless entry && record.is_a?(String) && record.match?(RECORD_REF) && input.is_a?(Hash)
+        resource, definition = entry[:resource], entry[:definition]
+        intent_id = Digest::UUID.uuid_v5(NAMESPACE, [ @context.actor_ref, @context.tenant_ref, @conversation, tool_call.id ].join("\n"))
+        # A replay of an already confirmed call reports it before re-checking the
+        # command grant, which a completed change may legitimately withdraw.
+        done = OperationRun.find_by(id: intent_id, actor_ref: @context.actor_ref, tenant_ref: @context.tenant_ref, status: "succeeded")
+        if done && done.origin == "assistant" && done.resource_key == resource.key.to_s && done.operation == definition.key.to_s
+          return { status: "reviewed", message: "The user already confirmed this proposal. Do not propose it again." }
+        end
+        access = Authorization::Access.new(@context, resource)
+        target = access.find!(record, action: definition.key)
+        values = proposal_values(resource, definition, target, input, intent_id)
+        return values if values.key?(:status)
+        surface = ToolViews.present(context: @context, resource: resource, definition: definition, record: target,
+          intent_ref: intent_id, input: ToolViews.wire_input(values),
+          assistant_call: { call_id: tool_call.id, conversation: @conversation })
+        { status: "presented", surface_id: surface.id,
+          message: "An interactive review was shown to the user. Nothing has changed; the user must confirm it." }
+      rescue AccessDenied => error
+        rejection(error.code)
+      rescue ::RailsToolViews::Error => error
+        rejection(error.code == "IDEMPOTENCY_CONFLICT" ? "IDEMPOTENCY_CONFLICT" : "NOT_FOUND")
+      end
+
+      private
+
+      # Opted-in operations on resources the actor may currently list.
+      def build_catalog
+        RailsAiAdmin.registry.resources.flat_map do |resource|
+          access = Authorization::Access.new(@context, resource)
+          begin
+            access.authorize!(:index)
+          rescue AccessDenied
+            next []
+          end
+          resource.assistant_operations.filter_map do |key|
+            definition = RailsAiAdmin.operation_registry.fetch(resource, key)
+            { resource: resource, definition: definition } if definition.custom? && definition.scope == :member
+          end
+        end
+      end
+
+      # Typed values of a new or replayed intent for this exact tool call.
+      def proposal_values(resource, definition, target, input, intent_id)
+        existing = OperationRun.find_by(id: intent_id, actor_ref: @context.actor_ref, tenant_ref: @context.tenant_ref)
+        unless existing
+          begin
+            proposal = Operations::Runner.new.preflight(context: @context, resource: resource, operation: definition.key,
+              target_id: target.id, expected_version: RecordVersion.of(target), input: input, origin: :assistant, intent_id: intent_id)
+          rescue ActiveRecord::RecordNotUnique
+            existing = OperationRun.find_by(id: intent_id, actor_ref: @context.actor_ref, tenant_ref: @context.tenant_ref)
+          end
+          if proposal.is_a?(Operations::Result)
+            declared = definition.handler_class.input.map { |field| field.name.to_s }
+            return { status: "rejected", code: proposal.code, fields: (proposal.errors.keys & declared).sort }
+          end
+          return proposal.values if proposal
+        end
+        raise AccessDenied unless existing && existing.origin == "assistant" && existing.resource_key == resource.key.to_s &&
+          existing.operation == definition.key.to_s && existing.target_id == target.id.to_s
+        raise AccessDenied, "IDEMPOTENCY_CONFLICT" unless existing.status == "proposed"
+        result = InputSchema.new(definition.fields(Authorization::Access.new(@context, resource), target)).coerce(input, time_zone: @context.time_zone)
+        raise AccessDenied, "IDEMPOTENCY_CONFLICT" unless result.valid? && InputSchema.digest(result.values) == existing.input_digest
+        result.values
+      end
+
+      MESSAGES = {
+        "NOT_FOUND" => "That record or operation is not available to this user.",
+        "VALIDATION_FAILED" => "The proposed input is invalid for this operation.",
+        "CONFLICT" => "The record changed; look it up again before proposing.",
+        "IDEMPOTENCY_CONFLICT" => "This tool call was already used for a different proposal.",
+        "INVALID_TOOL_CALL" => "This proposal must come from a tool call."
+      }.freeze
+
+      def rejection(code)
+        code = MESSAGES.key?(code) ? code : "NOT_FOUND"
+        { status: "rejected", code: code, message: MESSAGES.fetch(code) }
+      end
+    end
+  end
+end

data/lib/rails_ai_admin/integrations/tool_views.rb

@@ -0,0 +1,367 @@
+# frozen_string_literal: true
+
+require "json"
+
+module RailsAiAdmin
+  module Integrations
+    # Admin review Surfaces on the host-owned rails_tool_views runtime.
+    #
+    # Required only when `config.surfaces` is enabled, so conventional boot never
+    # loads rails_tool_views. The admin reads none of the host's global
+    # rails_tool_views settings (resolver, parent controller, adapter,
+    # auto_deliver) and changes none of them. Admin endpoints pass an explicit
+    # `raa:` Scope and bind the current admin Context for the duration of one
+    # call; policy and handler deny when no matching Context is bound, so another
+    # route (such as the host's product engine mount) can never act on them.
+    module ToolViews
+      KEY = "raa_operation_review"
+      VERSION = "1"
+      PARTIAL = "rails_ai_admin/surfaces/operation_review"
+      CONTEXT_KEY = :rails_ai_admin_surface_context
+      UUID = "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
+      MAX_INPUT_BYTES = 16_384
+      # Props hold only a server intent reference and its canonical wire input,
+      # so the component digest never depends on reloadable host code.
+      SCHEMA = {
+        type: "object", additionalProperties: false, required: %w[intent input],
+        properties: { intent: { type: "string", pattern: UUID, maxLength: 36 }, input: { type: "string", maxLength: MAX_INPUT_BYTES } }
+      }.freeze
+      CONFIRM_SCHEMA = { type: "object", additionalProperties: false, properties: {} }.freeze
+      # Business outcomes are recorded on the Surface with their failure audit.
+      TERMINAL = {
+        "CONFLICT" => "The record changed or was busy. Start a new review from the record.",
+        "APPROVAL_EXPIRED" => "This review expired. Start a new review from the record.",
+        "APPROVAL_INVALIDATED" => "Access or the operation changed. Start a new review from the record.",
+        "APPROVAL_REQUIRED" => "This operation needs a new review.",
+        "VALIDATION_FAILED" => "The operation rejected this input. Start a new review from the record.",
+        "IDEMPOTENCY_CONFLICT" => "This review no longer matches the recorded operation."
+      }.freeze
+      Review = ::Data.define(:run, :resource, :definition, :access, :record)
+      ASSISTANT_ADAPTER = "raa_assistant"
+
+      class << self
+        def available?
+          defined?(::RailsToolViews::Registry) ? true : false
+        end
+
+        # Re-registers after a host `reset_registry!`. The contract is constant,
+        # so an existing registration must be exactly this one.
+        def ensure_registered!
+          raise ConfigurationError, "rails_tool_views is not loaded" unless available?
+          component = begin
+            ::RailsToolViews.registry.fetch(KEY)
+          rescue ::RailsToolViews::Error => error
+            raise unless error.code == "UNKNOWN_COMPONENT"
+            register
+          end
+          unless component.policy.equal?(POLICY) && component.actions.fetch("confirm").handler.equal?(CONFIRM) &&
+              component.actions["dismiss"]&.handler.equal?(DISMISS)
+            raise ConfigurationError, "#{KEY} is registered by other code"
+          end
+          component
+        end
+
+        def scope_for(context)
+          raise AccessDenied, "UNAUTHENTICATED" unless context.is_a?(Context)
+          ::RailsToolViews::Scope.new(actor: context.actor_ref, tenant: context.tenant_ref)
+        end
+
+        # Binds the current admin Context for one admin endpoint call.
+        def with_context(context)
+          raise AccessDenied, "UNAUTHENTICATED" unless context.is_a?(Context)
+          state = ActiveSupport::IsolatedExecutionState
+          previous = state[CONTEXT_KEY]
+          state[CONTEXT_KEY] = context
+          yield
+        ensure
+          state[CONTEXT_KEY] = previous if state
+        end
+
+        def current_context = ActiveSupport::IsolatedExecutionState[CONTEXT_KEY]
+
+        # Presents (or replays) the review Surface for an unconsumed intent. A
+        # native intent replays per intent; an assistant intent belongs to its
+        # chat and replays per persisted tool call.
+        def present(context:, resource:, definition:, record:, intent_ref:, input:, chat: nil, call_id: nil, assistant_call: nil)
+          ensure_registered!
+          if definition.custom?
+            raise AccessDenied unless resource.surface_operation?(definition.key) && definition.scope == :member
+          else
+            # A native create, update or delete is reviewed here only when the
+            # assistant proposed it and the resource allows that change.
+            raise AccessDenied unless (chat || assistant_call) && resource.assistant_change?(definition.key)
+          end
+          raise AccessDenied if chat && assistant_call
+          origin = chat || assistant_call ? "assistant" : "ui"
+          raise AccessDenied if assistant_call && definition.custom? && !resource.assistant_operation?(definition.key)
+          raise AccessDenied unless intent_ref.is_a?(String) && intent_ref.match?(/\A[0-9a-f-]{36}\z/)
+          raise AccessDenied if chat && !(call_id.is_a?(String) && chat.current_for?(context) && chat.actor_ref == context.actor_ref && chat.tenant_ref == context.tenant_ref)
+          run = OperationRun.find_by(id: intent_ref, actor_ref: context.actor_ref, tenant_ref: context.tenant_ref)
+          unless run && run.id == intent_ref && run.resource_key == resource.key.to_s && run.operation == definition.key.to_s &&
+              run.target_id == record.id&.to_s && run.status == "proposed" && run.origin == origin && run.parent_run_id.nil?
+            raise AccessDenied
+          end
+          raise AccessDenied, "APPROVAL_EXPIRED" unless run.expires_at && run.expires_at > Time.current
+          raise AccessDenied, "APPROVAL_INVALIDATED" unless run.security_version == context.security_version
+          wire = canonical_input(input)
+          raise AccessDenied, "APPROVAL_INVALIDATED" unless run.input_digest && run.input_digest == InputSchema.digest(input_values(context, resource, definition, record, wire))
+          reference, correlation = if chat
+            [ chat.context_reference, { adapter: ASSISTANT_ADAPTER, call_id: call_id, context: chat.context_reference } ]
+          elsif assistant_call
+            [ assistant_call.fetch(:conversation), { adapter: "raa_assistant", call_id: assistant_call.fetch(:call_id), context: assistant_call.fetch(:conversation) } ]
+          else
+            [ "raa:intent:#{run.id}", { adapter: "raa_native_review", call_id: run.id, context: "raa:intent:#{run.id}" } ]
+          end
+          with_context(context) do
+            ::RailsToolViews.present(KEY, props: { "intent" => run.id, "input" => wire }, scope: scope_for(context),
+              context: reference, correlation: correlation)
+          end
+        end
+
+        # The Surface an earlier attempt presented for this persisted tool call,
+        # so a retried tool does not prepare a second intent. Byte-exact match.
+        def assistant_surface(context, chat, call_id)
+          lookup = { adapter: ASSISTANT_ADAPTER, call_id: call_id, context_ref: chat.context_reference,
+            actor_ref: context.actor_ref, tenant_ref: context.tenant_ref }
+          prior = ::RailsToolViews::Presentation.find_by(lookup)
+          return unless prior && lookup.all? { |attribute, value| prior.public_send(attribute) == value }
+          with_context(context) { ::RailsToolViews.restore(prior.surface_id, scope: scope_for(context)) }
+        rescue ::RailsToolViews::Error
+          nil
+        end
+
+        # Canonical wire strings for typed operation values, as native forms send.
+        def wire_input(values)
+          values.to_h do |name, value|
+            wire = case value
+            when BigDecimal then value.to_s("F")
+            when Time, ActiveSupport::TimeWithZone then value.utc.iso8601(6)
+            when Date then value.iso8601
+            else value
+            end
+            [ name.to_s, wire ]
+          end
+        end
+
+        # Current authorized review for props, or nil. Never trusts the Surface.
+        def review(context, props)
+          return unless context.is_a?(Context) && props.is_a?(Hash) && props["intent"].is_a?(String)
+          run = OperationRun.find_by(id: props["intent"], actor_ref: context.actor_ref, tenant_ref: context.tenant_ref)
+          return unless run && run.id == props["intent"] && run.parent_run_id.nil? && run.selection_id.nil?
+          resource = RailsAiAdmin.registry.fetch(run.resource_key)
+          definition = RailsAiAdmin.operation_registry.fetch(resource, run.operation)
+          if definition.custom?
+            return unless definition.scope == :member && resource.surface_operation?(definition.key)
+          else
+            return unless run.origin == "assistant" && resource.assistant_change?(definition.key)
+          end
+          access = Authorization::Access.new(context, resource)
+          Review.new(run, resource, definition, access, review_record(access, run))
+        rescue AccessDenied, ConfigurationError, ActiveRecord::RecordNotFound
+          nil
+        end
+
+        def authorize(access)
+          context = current_context
+          return false unless context.is_a?(Context) && access.actor == context.actor_ref && access.tenant == context.tenant_ref
+          review = review(context, access.props)
+          return false unless review
+          case access.operation
+          when :present then review.run.status == "proposed"
+          # A completed review is a receipt: like native replay it needs the
+          # independent receipt grant, not the (possibly lapsed) command grant.
+          when :read then review.run.status != "succeeded" || receipt?(review)
+          when :action then %w[confirm dismiss].include?(access.action)
+          else false
+          end
+        end
+
+        # The record a review is about: a new one for a proposed create, the
+        # created one afterwards, and none once a delete succeeded.
+        def review_record(access, run)
+          case run.operation
+          when "create" then run.status == "succeeded" ? access.find!(run.record_id) : access.relation.new
+          when "destroy" then run.status == "succeeded" ? nil : access.find!(run.target_id)
+          else access.find!(run.target_id)
+          end
+        end
+
+        # How a review names its record in the conversation and on the card.
+        def subject(review)
+          singular = review.resource.label.singularize
+          return "#{singular} ##{review.run.target_id}" if review.record.nil?
+          return "a new #{singular.downcase_first}" unless review.record.persisted?
+          review.access.record_label(review.record)
+        end
+
+        def receipt?(review)
+          # A native change's result is the record itself, behind its list grant.
+          return review.access.authorize!(:index) unless review.definition.custom?
+          review.access.authorize_receipt!(review.definition.key, review.record)
+        rescue AccessDenied
+          false
+        end
+
+        # The human's own submission of the Surface form is the confirmation.
+        def confirm(request)
+          context = current_context
+          review = review(context, request.props) if context && request.actor == context.actor_ref && request.tenant == context.tenant_ref
+          raise ::RailsToolViews::Error.new("NOT_ALLOWED", status: 403) unless review
+          run = review.run
+          result = Operations::Runner.new.execute(context: context, intent_ref: run.id, input: JSON.parse(request.props.fetch("input")),
+            human_confirmed: true, origin: :surface, binding: { resource_key: run.resource_key, operation: run.operation, target_id: run.target_id })
+          if result.success?
+            message = result.replayed ? "This operation was already completed. No second change was made." : "Operation completed."
+            applied = run.operation == "create" ? "The record was created with id #{result.record_id}." : "The change was applied."
+            continue_chat(context, request, review, result.replayed ? "It had already been applied; no second change was made." : applied)
+            ::RailsToolViews::Transition.new(state: { "outcome" => "succeeded", "message" => message }, agent: false)
+          elsif TERMINAL.key?(result.code)
+            continue_chat(context, request, review, "It was not applied (#{result.code}): #{TERMINAL.fetch(result.code)}")
+            ::RailsToolViews::Transition.new(state: { "outcome" => "rejected", "code" => result.code, "message" => TERMINAL.fetch(result.code) }, agent: false)
+          elsif result.code == "NOT_FOUND"
+            raise ::RailsToolViews::Error.new("NOT_ALLOWED", status: 403)
+          else
+            # Nothing committed; the Surface revision is unchanged and retry is safe.
+            raise ::RailsToolViews::Error.new("OPERATION_FAILED", status: 503, message: "The operation could not complete. Nothing was changed; try again.")
+          end
+        end
+
+        # Declining is a decision too (RAA-019): the unapproved intent expires
+        # at once, nothing else changes, and a chat hears about it once.
+        def dismiss(request)
+          context = current_context
+          review = review(context, request.props) if context && request.actor == context.actor_ref && request.tenant == context.tenant_ref
+          raise ::RailsToolViews::Error.new("NOT_ALLOWED", status: 403) unless review
+          expired = OperationRun.where(id: review.run.id, status: "proposed", approved_by_ref: nil)
+            .update_all(expires_at: Time.current, updated_at: Time.current)
+          raise ::RailsToolViews::Error.new("CONFLICT", status: 409, message: "This review was already decided.") unless expired == 1
+          continue_chat(context, request, review, "Nothing was changed.", decision: "dismissed")
+          ::RailsToolViews::Transition.new(state: { "outcome" => "dismissed", "message" => "Dismissed. Nothing was changed." }, agent: false)
+        end
+
+        # The visible before/after values the operation's pure preflight
+        # proposes, as the native confirmation page shows them. Empty once the
+        # review cannot be confirmed or the preview is no longer valid.
+        def proposed_changes(review, wire)
+          return [] unless review.run.status == "proposed"
+          return native_changes(review, wire) unless review.definition.custom?
+          context = review.access.context
+          preview = Operations::Runner.new.preview(context: context, resource: review.resource, operation: review.definition.key,
+            target_id: review.record.id, expected_version: review.run.expected_version, input: JSON.parse(wire), origin: :surface)
+          return [] unless preview.is_a?(Operations::Runner::Preview)
+          readable = review.access.fields(:read, review.record, view: :show).index_by { |field| field.name.to_s }
+          preview.changes.filter_map do |name, change|
+            field = readable[name]
+            next unless field
+            [ field, field.format(change["before"], time_zone: context.time_zone), field.format(change["after"], time_zone: context.time_zone) ]
+          end
+        rescue AccessDenied, ConfigurationError, JSON::ParserError
+          []
+        end
+
+        # Typed display values. While proposed, only the actor's current input
+        # grants; once committed, the recorded input through the operation's
+        # declared contract (as receipt replay does), behind the receipt grant.
+        def display_values(review, wire)
+          # Native changes show before and after instead (native_changes).
+          return [] unless review.definition.custom?
+          values = JSON.parse(wire)
+          fields = if review.run.status == "succeeded"
+            review.definition.handler_class.input
+          else
+            begin
+              review.definition.fields(review.access, review.record)
+            rescue AccessDenied
+              []
+            end
+          end
+          fields.filter_map do |field|
+            next unless values.key?(field.name.to_s)
+            text = begin
+              field.format(field.coerce(values[field.name.to_s], time_zone: review.access.context.time_zone), time_zone: review.access.context.time_zone)
+            rescue ArgumentError
+              "Unavailable"
+            end
+            [ field, text ]
+          end
+        rescue JSON::ParserError
+          []
+        end
+
+        # Before and after for a native create or update, through the actor's
+        # read grants; references show their labels. A field the actor may
+        # write but not read shows only that it will be set.
+        def native_changes(review, wire)
+          return [] if review.run.operation == "destroy"
+          context = review.access.context
+          values = input_values(context, review.resource, review.definition, review.record, wire)
+          persisted = review.record.persisted?
+          readable = review.access.fields(:read, persisted ? review.record : nil, view: :show).index_by { |field| field.name.to_s }
+          current = persisted ? review.access.project(review.record, view: :show) : {}
+          resolver = Fields::Association.new(context, review.resource)
+          fields = review.resource.fields.index_by { |field| field.name.to_s }
+          values.filter_map do |name, after|
+            field = fields[name]
+            next unless field
+            before = current[name]
+            next if persisted && before == after
+            show = ->(value) { readable.key?(name) ? native_text(field, value, resolver, context) : I18n.t("rails_ai_admin.surfaces.hidden_value") }
+            [ field, persisted ? show.call(before) : "—", show.call(after) ]
+          end
+        rescue AccessDenied, ConfigurationError, JSON::ParserError
+          []
+        end
+
+        def native_text(field, value, resolver, context)
+          return "—" if value.nil?
+          case field.scalar_type
+          when :belongs_to then resolver.reference(field, value.to_s).label.to_s
+          when :references then Array(value).map { |id| resolver.reference(field, id).label.to_s }.join(", ").presence || "—"
+          else field.format(value, time_zone: context.time_zone)
+          end
+        end
+
+        private
+
+        # Same transaction as the Surface revision; nothing is admitted when
+        # the confirmation rolls back.
+        def continue_chat(context, request, review, outcome, decision: "confirmed")
+          return unless RailsAiAdmin.configuration.assistant
+          require "rails_ai_admin/assistant"
+          Assistant::Continuation.admit!(context: context, context_ref: request.context_ref, review: review, outcome: outcome, decision: decision)
+        rescue AccessDenied
+          # A closed chat never blocks the human's committed business outcome.
+          nil
+        end
+
+        def register
+          ::RailsToolViews.register(KEY, description: "Admin operation review", version: VERSION, schema: SCHEMA, partial: PARTIAL,
+            policy: POLICY, actions: { confirm: { schema: CONFIRM_SCHEMA, policy: POLICY, handler: CONFIRM },
+              dismiss: { schema: CONFIRM_SCHEMA, policy: POLICY, handler: DISMISS } }, expose_to: [])
+        rescue ::RailsToolViews::Error => error
+          raise unless error.code == "DUPLICATE_COMPONENT"
+          ::RailsToolViews.registry.fetch(KEY)
+        end
+
+        def canonical_input(input)
+          raise AccessDenied, "INVALID_QUERY" unless input.is_a?(Hash)
+          stringified = input.to_h { |key, value| [ key.to_s, value ] }
+          wire = JSON.generate(stringified.sort.to_h)
+          raise AccessDenied, "INVALID_QUERY" if wire.bytesize > MAX_INPUT_BYTES
+          wire
+        end
+
+        def input_values(context, resource, definition, record, wire)
+          access = Authorization::Access.new(context, resource)
+          result = InputSchema.new(definition.fields(access, record), partial: definition.key == "update" && !definition.custom?).coerce(JSON.parse(wire), time_zone: context.time_zone)
+          raise AccessDenied, "APPROVAL_INVALIDATED" unless result.valid?
+          result.values
+        end
+      end
+
+      POLICY = ->(access) { ToolViews.authorize(access) }
+      CONFIRM = ->(request) { ToolViews.confirm(request) }
+      DISMISS = ->(request) { ToolViews.dismiss(request) }
+    end
+  end
+end