rails_ai_admin 0.1.0

data/lib/rails_ai_admin/assistant/tools.rb

@@ -0,0 +1,477 @@
+# frozen_string_literal: true
+
+require "json"
+
+module RailsAiAdmin
+  module Assistant
+    # Tool state for one claimed turn: the freshly resolved Context, the chat
+    # and a fence that stops a worker whose lease was reassigned.
+    # conversation is the server-owned reference of a session without a chat
+    # (an MCP client); its proposals become reviews opened by URL.
+    Session = ::Data.define(:context, :chat, :fence, :conversation) do
+      def initialize(context:, chat:, fence:, conversation: nil) = super
+      # Registered resources this actor may currently expose to the model.
+      def resources
+        RailsAiAdmin.registry.resources.select { |resource| exposed?(resource) }
+      end
+
+      # Unknown, hidden and unexposed resources are indistinguishable.
+      def resource(key)
+        raise AccessDenied unless key.is_a?(String) && key.match?(/\A[a-z][a-z0-9_]{0,63}\z/)
+        resource = RailsAiAdmin.registry.fetch(key)
+        raise AccessDenied unless exposed?(resource)
+        resource
+      rescue ConfigurationError, KeyError
+        raise AccessDenied
+      end
+
+      def access(resource) = Authorization::Access.new(context, resource)
+
+      private
+
+      def exposed?(resource)
+        access(resource).authorize_assistant!
+      rescue AccessDenied
+        false
+      end
+    end
+
+    # Base for admin tools. Each call checks the turn fence and current grants.
+    # Results are bounded JSON data for the model; they grant nothing.
+    class Tool < ::RubyLLM::Tool
+      MAX_RESULT_BYTES = 16_384
+      MESSAGES = {
+        "NOT_FOUND" => "Not found or not available to this user.",
+        "INVALID_QUERY" => "The request was not valid for this resource.",
+        "CONFLICT" => "The record changed. Fetch it again before proposing a change.",
+        "VALIDATION_FAILED" => "The proposed input is not valid.",
+        "UNAVAILABLE" => "This capability is not available."
+      }.freeze
+
+      def initialize(session)
+        super()
+        @session = session
+      end
+
+      def execute(tool_call: nil, **arguments)
+        @session.fence.call
+        bounded(perform(tool_call: tool_call, **arguments))
+      rescue ArgumentError
+        # Missing or unknown model-supplied keywords.
+        failure("INVALID_QUERY")
+      rescue AccessDenied => error
+        failure(error.code == "INVALID_QUERY" ? "INVALID_QUERY" : error.code == "CONFLICT" ? "CONFLICT" : "NOT_FOUND")
+      rescue ConfigurationError
+        failure("UNAVAILABLE")
+      end
+
+      private
+
+      def failure(code, **extra) = { "error" => code, "message" => MESSAGES.fetch(code, MESSAGES["UNAVAILABLE"]), **extra }
+
+      # A chat shows the review in the conversation; a session without one
+      # (MCP) records it under its conversation reference for the person to
+      # open in the admin.
+      def present_review(tool_views, resource, definition, record, proposal, tool_call)
+        common = { context: @session.context, resource: resource, definition: definition, record: record,
+          intent_ref: proposal.intent.id, input: tool_views.wire_input(proposal.values) }
+        if @session.chat
+          tool_views.present(**common, chat: @session.chat, call_id: tool_call.id)
+        else
+          tool_views.present(**common, assistant_call: { conversation: @session.conversation, call_id: tool_call.id })
+        end
+      end
+
+      def acknowledgment(surface)
+        message = @session.chat ? "A review is shown to the user. Nothing has changed yet; a later message reports the confirmed result." :
+          "A review is waiting in the admin. Nothing has changed until the user opens review_url and confirms it."
+        { "status" => "awaiting_human_confirmation", "surface" => surface.id, "message" => message }
+      end
+
+      def bounded(result)
+        raise ConfigurationError, "Tool result must be a Hash" unless result.is_a?(Hash)
+        return result if JSON.generate(result).bytesize <= MAX_RESULT_BYTES
+        if result["records"].is_a?(Array)
+          records = result["records"].dup
+          records.pop while records.any? && JSON.generate(result.merge("records" => records, "truncated" => true)).bytesize > MAX_RESULT_BYTES
+          return result.merge("records" => records, "truncated" => true)
+        end
+        failure("UNAVAILABLE")
+      end
+
+      def time_zone = @session.context.time_zone
+
+      # Typed JSON for the model (RAA-017): null stays null, booleans and
+      # integers keep their JSON types, decimals are exact strings padded to
+      # their scale, dates and times are ISO 8601, a select is {value, label}
+      # and a reference is {id, label, resource}. A registered field type keeps
+      # its formatted text, because its formatter may deliberately redact.
+      def typed(field, value, references)
+        return nil if value.nil?
+        return field.format(value, time_zone: time_zone).truncate(500) if field.plugin?
+        case field.scalar_type
+        when :boolean, :integer then value
+        when :decimal then field.format_decimal(value)
+        when :date then value.iso8601
+        when :datetime then value.in_time_zone(time_zone).iso8601
+        when :time then field.format(value, time_zone: time_zone)
+        when :json then JSON.generate(value).truncate(2000)
+        when :references
+          Array(value).first(50).map do |id|
+            reference = references.reference(field, id)
+            { "id" => reference.id, "label" => reference.label.to_s.truncate(200), "resource" => reference.visible ? reference.resource_key.to_s : nil }
+          end
+        when :rich_text then field.format(value, time_zone: time_zone).truncate(2000)
+        when :files then Array(value).map { |file| { "filename" => file.filename.truncate(200), "content_type" => file.content_type, "byte_size" => file.byte_size } }
+        when :file then { "filename" => value.filename.truncate(200), "content_type" => value.content_type, "byte_size" => value.byte_size }
+        when :select then { "value" => value.to_s, "label" => field.format(value, time_zone: time_zone) }
+        when :belongs_to
+          reference = references.reference(field, value.to_s)
+          { "id" => reference.id, "label" => reference.label.to_s.truncate(200), "resource" => reference.visible ? reference.resource_key.to_s : nil }
+        else value.to_s.truncate(500)
+        end
+      end
+
+      def values(access, record, view, references)
+        fields = access.fields(:read, record, view: view).index_by { |field| field.name.to_s }
+        access.project(record, view: view).filter_map do |name, value|
+          field = fields[name]
+          [ name, typed(field, value, references) ] if field
+        end.to_h
+      end
+
+      def reference_resolver(access) = Fields::Association.new(access.context, access.resource)
+
+      def record_entry(access, record, view, references = reference_resolver(access))
+        { "id" => record.id.to_s, "label" => access.record_label(record, view: view), "fields" => values(access, record, view, references) }
+      end
+
+      # Records the actor may list but not open are left out, as on the list
+      # page (RAA-001), and counted so the model can say so.
+      def record_entries(access, records, view)
+        resolver = reference_resolver(access)
+        access.fields(:read, nil, view: view).select { |field| field.scalar_type == :belongs_to }.each do |field|
+          resolver.prime(field, records.filter_map { |record| record.has_attribute?(field.column) ? record.read_attribute(field.column)&.to_s : nil })
+        end
+        omitted = 0
+        entries = records.filter_map do |record|
+          record_entry(access, record, view, resolver)
+        rescue AccessDenied
+          omitted += 1
+          nil
+        end
+        [ entries, omitted ]
+      end
+
+      def wire_filters(filters)
+        return nil if filters.nil? || filters == {}
+        raise AccessDenied, "INVALID_QUERY" unless filters.is_a?(Hash) && filters.size <= Queries::List::MAX_FILTER_CONDITIONS
+        filters.to_h do |name, conditions|
+          raise AccessDenied, "INVALID_QUERY" unless conditions.is_a?(Hash)
+          [ name.to_s, conditions.to_h { |operator, value| [ operator.to_s, scalar(value) ] } ]
+        end
+      end
+
+      def scalar(value)
+        case value
+        when String then value
+        when Integer, Float, true, false then value.to_s
+        else raise AccessDenied, "INVALID_QUERY"
+        end
+      end
+
+      # The assistant sees the whole policy relation unless it names a granted
+      # list tab; a default tab never applies silently (RAA-007).
+      def list_scope(scope)
+        return Queries::NamedScope::NONE if scope.nil?
+        raise AccessDenied, "INVALID_QUERY" unless scope.is_a?(String) && scope.match?(Queries::NamedScope::NAME)
+        scope
+      end
+    end
+
+    class ListResources < Tool
+      description "List the admin resources this user may ask about. Call this first to learn resource keys."
+      parameters({ "type" => "object", "properties" => {}, "additionalProperties" => false })
+
+      def self.tool_name = "list_resources"
+
+      private
+
+      def perform(tool_call:)
+        { "resources" => @session.resources.map { |resource| { "key" => resource.key.to_s, "label" => resource.label } } }
+      end
+    end
+
+    class DescribeResource < Tool
+      description "Describe one resource: readable fields, search, filters and the changes you may propose."
+      parameters({ "type" => "object", "required" => [ "resource" ], "additionalProperties" => false,
+        "properties" => { "resource" => { "type" => "string", "description" => "A key from list_resources" } } })
+
+      def self.tool_name = "describe_resource"
+
+      private
+
+      def perform(tool_call:, resource:)
+        resource = @session.resource(resource)
+        access = @session.access(resource)
+        result = {
+          "key" => resource.key.to_s, "label" => resource.label,
+          "fields" => access.fields(:read, nil, view: :show).map { |field| field_entry(field) },
+          # Match mode per field: "prefix" means "Love" does not find "Ada Lovelace" (RAA-021).
+          "search" => access.fields(:search).map { |field| { "field" => field.name.to_s, "match" => (field.options[:searchable] == true ? :prefix : field.options[:searchable]).to_s } },
+          "filters" => access.fields(:filter).map { |field| { "field" => field.name.to_s, "operators" => field.filter_operators.map(&:to_s) } },
+          "sort" => access.fields(:sort).map { |field| field.name.to_s },
+          # Search and count apply no list tab unless one is named (RAA-007).
+          "scopes" => access.named_scopes.map { |definition| { "name" => definition.name.to_s, "label" => definition.label, "default_in_ui" => definition.default? } }
+        }
+        if RailsAiAdmin.configuration.surfaces
+          result["operations"] = operations(resource, access)
+          result["changes"] = changes(resource, access)
+        end
+        result
+      end
+
+      # Native changes this resource lets the assistant propose, with the
+      # fields the user may set on create or update (never passwords or files).
+      def changes(resource, access)
+        %w[create update destroy].filter_map do |action|
+          next unless resource.assistant_change?(action)
+          entry = { "action" => action }
+          unless action == "destroy"
+            fields = access.fields(:write, action == "create" ? access.relation.new : nil, operation: action.to_sym)
+              .reject { |field| ProposeChange::UNSUPPORTED.include?(field.scalar_type) }
+            entry["fields"] = fields.map { |field| field_entry(field).merge("required" => action == "create" && field.options[:required] == true) }
+          end
+          entry
+        end
+      end
+
+      def field_entry(field)
+        entry = { "name" => field.name.to_s, "label" => field.label, "type" => field.scalar_type.to_s }
+        # Operation inputs declare enum values; without them a model can only guess.
+        entry["choices"] = field.choice_options.map { |label, value| { "value" => value, "label" => label } } if %i[select enum].include?(field.scalar_type)
+        entry
+      end
+
+      # Declared contracts only. Member grants depend on the record, so each
+      # proposal is authorized against its record by propose_operation.
+      def operations(resource, _access)
+        RailsAiAdmin.operation_registry.custom(resource).filter_map do |definition|
+          next unless definition.scope == :member && resource.assistant_operation?(definition.key)
+          { "key" => definition.key.to_s, "description" => definition.description.to_s.truncate(200),
+            "input" => definition.handler_class.input.map { |field| field_entry(field).merge("required" => field.options[:required] == true) } }
+        end
+      end
+    end
+
+    class SearchRecords < Tool
+      PAGE_LIMIT = 20
+      MAX_RECORDS = 1_000
+      description "Search one resource's records with optional text, typed filters, a list scope and a sort. Returns up to 20 records. " \
+        "Every record you may see is searched unless you pass scope. To count records, use count_records instead of paging. " \
+        "When has_more is true, pass next_offset as offset to continue, including after truncation."
+      parameters({ "type" => "object", "required" => [ "resource" ], "additionalProperties" => false,
+        "properties" => {
+          "resource" => { "type" => "string" },
+          "query" => { "type" => "string", "maxLength" => 200, "description" => "Text matched against searchable fields with each field's match mode" },
+          "filters" => { "type" => "object", "description" => "Field name to {\"eq\"|\"gte\"|\"lte\": value}; use select values, not labels",
+            "additionalProperties" => { "type" => "object", "additionalProperties" => { "type" => %w[string number boolean] } } },
+          "scope" => { "type" => "string", "description" => "Optional scope name from describe_resource" },
+          "sort" => { "type" => "string", "description" => "Optional sortable field from describe_resource" },
+          "direction" => { "type" => "string", "enum" => %w[asc desc] },
+          "page" => { "type" => "integer", "minimum" => 1, "maximum" => 50 },
+          "offset" => { "type" => "integer", "minimum" => 0, "maximum" => MAX_RECORDS - 1, "description" => "The next_offset returned by the previous result" }
+        } })
+
+      def self.tool_name = "search_records"
+
+      private
+
+      def perform(tool_call:, resource:, query: nil, filters: nil, scope: nil, sort: nil, direction: nil, page: 1, offset: nil)
+        resource = @session.resource(resource)
+        access = @session.access(resource)
+        raise AccessDenied, "INVALID_QUERY" unless page.is_a?(Integer) && page.between?(1, 50)
+        raise AccessDenied, "INVALID_QUERY" unless sort.nil? || sort.is_a?(String) && sort.match?(Field::NAME)
+        raise AccessDenied, "INVALID_QUERY" unless direction.nil? || %w[asc desc].include?(direction)
+        offset = (page - 1) * PAGE_LIMIT if offset.nil?
+        raise AccessDenied, "INVALID_QUERY" unless offset.is_a?(Integer) && offset.between?(0, MAX_RECORDS - 1)
+        result = Queries::List.new(@session.context, resource).call(search: query.presence, page: page.to_s, filters: wire_filters(filters),
+          scope: list_scope(scope), sort: sort, direction: direction || "asc", page_size: [ PAGE_LIMIT, MAX_RECORDS - offset ].min, offset: offset)
+        records, omitted = record_entries(access, result.records, :index)
+        { "resource" => resource.key.to_s, "applied_scope" => result.scope,
+          "applied_sort" => result.sort ? { "field" => result.sort, "direction" => result.direction } : nil,
+          "page" => result.number, "offset" => offset, "has_more" => result.has_next,
+          "omitted" => omitted, "records" => records }
+      end
+
+      # Leave room for continuation metadata before applying the byte bound.
+      # Advance by what the model actually saw, not the number queried.
+      def bounded(result)
+        return result if result["error"]
+        result = super(result.merge("next_offset" => MAX_RECORDS, "limit_reached" => false))
+        records = result.fetch("records")
+        return failure("UNAVAILABLE") if records.empty? && result["truncated"]
+        next_offset = result.fetch("offset") + records.size
+        more = result["has_more"] || result["truncated"] == true
+        result.merge("next_offset" => more && next_offset < MAX_RECORDS ? next_offset : nil,
+          "has_more" => more && next_offset < MAX_RECORDS, "limit_reached" => more && next_offset >= MAX_RECORDS)
+      end
+    end
+
+    # One bounded number, so "how many" never means paging (roadmap
+    # "aggregate tools"). Same grants, filters and scope rule as search.
+    class CountRecords < Tool
+      description "Count one resource's records matching optional text, typed filters and a list scope. " \
+        "Every record you may see is counted unless you pass scope. Counts above the cap are reported as capped."
+      parameters({ "type" => "object", "required" => [ "resource" ], "additionalProperties" => false,
+        "properties" => {
+          "resource" => { "type" => "string" },
+          "query" => { "type" => "string", "maxLength" => 200 },
+          "filters" => { "type" => "object", "description" => "Field name to {\"eq\"|\"gte\"|\"lte\": value}",
+            "additionalProperties" => { "type" => "object", "additionalProperties" => { "type" => %w[string number boolean] } } },
+          "scope" => { "type" => "string", "description" => "Optional scope name from describe_resource" }
+        } })
+
+      def self.tool_name = "count_records"
+
+      private
+
+      def perform(tool_call:, resource:, query: nil, filters: nil, scope: nil)
+        resource = @session.resource(resource)
+        result = Queries::List.new(@session.context, resource).count(search: query.presence, filters: wire_filters(filters), scope: list_scope(scope))
+        { "resource" => resource.key.to_s, "applied_scope" => result.scope, "count" => result.count, "capped" => result.capped }
+      end
+    end
+
+    class GetRecord < Tool
+      description "Read one record's fields by resource key and id."
+      parameters({ "type" => "object", "required" => %w[resource id], "additionalProperties" => false,
+        "properties" => { "resource" => { "type" => "string" }, "id" => { "type" => "string", "maxLength" => 100 } } })
+
+      def self.tool_name = "get_record"
+
+      private
+
+      def perform(tool_call:, resource:, id:)
+        resource = @session.resource(resource)
+        access = @session.access(resource)
+        raise AccessDenied unless id.is_a?(String) && id.match?(Field::REFERENCE)
+        { "resource" => resource.key.to_s, "records" => [ record_entry(access, access.find!(id), :show) ] }
+      end
+    end
+
+    # Prepares a native intent and presents its review Surface. The human's own
+    # confirmation in that Surface is the only approval; this tool writes no
+    # business data and cannot confirm anything.
+    class ProposeOperation < Tool
+      description "Propose a change for the user to review. It does not change data: the user confirms or ignores the review shown in the conversation."
+      parameters({ "type" => "object", "required" => %w[resource id operation input], "additionalProperties" => false,
+        "properties" => {
+          "resource" => { "type" => "string" }, "id" => { "type" => "string", "maxLength" => 100 },
+          "operation" => { "type" => "string", "description" => "An operation key from describe_resource" },
+          "input" => { "type" => "object", "description" => "Input values for the operation's declared fields" }
+        } })
+
+      def self.tool_name = "propose_operation"
+
+      private
+
+      def perform(tool_call:, resource:, id:, operation:, input:)
+        raise ConfigurationError, "Surfaces are disabled" unless RailsAiAdmin.configuration.surfaces
+        raise ConfigurationError, "A persisted tool call is required" unless tool_call.respond_to?(:id) && tool_call.id.is_a?(String)
+        raise AccessDenied, "INVALID_QUERY" unless input.is_a?(Hash) && operation.is_a?(String) && id.is_a?(String)
+        resource = @session.resource(resource)
+        definition = RailsAiAdmin.operation_registry.fetch(resource, operation)
+        raise AccessDenied unless definition.custom? && definition.scope == :member && resource.assistant_operation?(definition.key)
+        tool_views = Assistant.tool_views
+        replay = @session.chat && tool_views.assistant_surface(@session.context, @session.chat, tool_call.id)
+        return acknowledgment(replay) if replay
+        record = @session.access(resource).find!(id, action: definition.key)
+        proposal = Operations::Runner.new.preflight(context: @session.context, resource: resource, operation: definition.key,
+          target_id: record.id, expected_version: RecordVersion.of(record), input: input, origin: :assistant)
+        if proposal.is_a?(Operations::Result)
+          return failure(proposal.code == "VALIDATION_FAILED" ? "VALIDATION_FAILED" : proposal.code == "CONFLICT" ? "CONFLICT" : "UNAVAILABLE",
+            "fields" => proposal.errors.keys.map(&:to_s))
+        end
+        acknowledgment(present_review(tool_views, resource, definition, record, proposal, tool_call))
+      end
+    end
+
+    # Prepares a native create, update or delete intent and presents its
+    # review. Nothing changes until the human confirms that review; the write
+    # then runs as the human, with a version check, through the shared Runner.
+    class ProposeChange < Tool
+      ACTIONS = %w[create update destroy].freeze
+      # Values a model cannot sensibly supply: secrets and uploads.
+      UNSUPPORTED = %i[password file files].freeze
+      description "Propose creating, updating or deleting one record. It does not change data: the user reviews and confirms or " \
+        "dismisses it in the conversation. For update, send only the fields to change. describe_resource lists the allowed changes."
+      parameters({ "type" => "object", "required" => %w[resource action], "additionalProperties" => false,
+        "properties" => {
+          "resource" => { "type" => "string" },
+          "action" => { "type" => "string", "enum" => ACTIONS },
+          "id" => { "type" => "string", "maxLength" => 100, "description" => "The record id; required for update and delete" },
+          "values" => { "type" => "object", "description" => "Field names and new values, typed as describe_resource reports" }
+        } })
+
+      def self.tool_name = "propose_change"
+
+      private
+
+      def perform(tool_call:, resource:, action:, id: nil, values: {})
+        raise ConfigurationError, "Surfaces are disabled" unless RailsAiAdmin.configuration.surfaces
+        raise ConfigurationError, "A persisted tool call is required" unless tool_call.respond_to?(:id) && tool_call.id.is_a?(String)
+        raise AccessDenied, "INVALID_QUERY" unless ACTIONS.include?(action) && values.is_a?(Hash) && (id.nil? || id.is_a?(String))
+        raise AccessDenied, "INVALID_QUERY" if action == "create" ? !id.nil? : id.nil?
+        raise AccessDenied, "INVALID_QUERY" if action == "destroy" ? values.any? : (action == "update" && values.empty?)
+        resource = @session.resource(resource)
+        raise AccessDenied unless resource.assistant_change?(action)
+        tool_views = Assistant.tool_views
+        replay = @session.chat && tool_views.assistant_surface(@session.context, @session.chat, tool_call.id)
+        return acknowledgment(replay) if replay
+        access = @session.access(resource)
+        record = action == "create" ? access.relation.new : access.find!(id, action: action.to_sym)
+        definition = RailsAiAdmin.operation_registry.fetch(resource, action)
+        by_name = resource.fields.index_by { |field| field.name.to_s }
+        raise AccessDenied, "INVALID_QUERY" if values.keys.any? { |name| UNSUPPORTED.include?(by_name[name.to_s]&.scalar_type) }
+        proposal = Operations::Runner.new.preflight(context: @session.context, resource: resource, operation: action,
+          target_id: action == "create" ? nil : record.id, expected_version: action == "create" ? nil : RecordVersion.of(record),
+          input: values.transform_keys(&:to_s), origin: :assistant)
+        if proposal.is_a?(Operations::Result)
+          return failure(proposal.code == "VALIDATION_FAILED" ? "VALIDATION_FAILED" : proposal.code == "CONFLICT" ? "CONFLICT" : "UNAVAILABLE",
+            "fields" => proposal.errors.to_h.transform_values { |messages| Array(messages).first(3) })
+        end
+        acknowledgment(present_review(tool_views, resource, definition, record, proposal, tool_call))
+      end
+    end
+
+    # A record's audited changes, behind the same view_history? grant as its
+    # History page. Field names follow the user's current grants.
+    class RecordHistory < Tool
+      LIMIT = 20
+      description "List the latest audited changes to one record: when, what kind, which fields and by whom. Values are never recorded."
+      parameters({ "type" => "object", "required" => %w[resource id], "additionalProperties" => false,
+        "properties" => { "resource" => { "type" => "string" }, "id" => { "type" => "string", "maxLength" => 100 } } })
+
+      def self.tool_name = "record_history"
+
+      private
+
+      def perform(tool_call:, resource:, id:)
+        resource = @session.resource(resource)
+        access = @session.access(resource)
+        raise AccessDenied unless id.is_a?(String) && id.match?(Field::REFERENCE)
+        record = access.find!(id)
+        page = Presentation::History.new(access, record).page
+        entries = page.entries.first(LIMIT).map do |entry|
+          { "at" => entry.at.in_time_zone(time_zone).iso8601, "change" => entry.operation, "saved" => entry.status == "succeeded",
+            "outcome" => entry.code, "fields" => entry.fields, "other_fields" => entry.hidden_fields,
+            "by" => entry.actor_ref == @session.context.actor_ref ? "the current user" : entry.actor_ref, "via" => entry.origin }
+        end
+        { "resource" => resource.key.to_s, "id" => record.id.to_s, "changes" => entries, "more" => page.entries.size > LIMIT || !page.older.nil? }
+      end
+    end
+
+    TOOLS = [ ListResources, DescribeResource, SearchRecords, CountRecords, GetRecord, RecordHistory ].freeze
+  end
+end

data/lib/rails_ai_admin/assistant/transcript.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+require "json"
+
+module RailsAiAdmin
+  module Assistant
+    # Display entries for one chat, rebuilt per request. Stored tool output is
+    # never shown as is: record references are re-read through current grants
+    # and Surfaces are restored through the admin scope and policy.
+    class Transcript
+      MESSAGE_LIMIT = 200
+      LINK_LIMIT = 20
+      Entry = ::Data.define(:kind, :text, :links, :surface_id, :at)
+      Link = ::Data.define(:resource_key, :id, :label)
+      ACTIVITY = {
+        "list_resources" => "Listed the available resources",
+        "describe_resource" => "Read the fields of %<resource>s",
+        "search_records" => "Searched %<resource>s",
+        "count_records" => "Counted records in %<resource>s",
+        "get_record" => "Opened a record in %<resource>s",
+        "propose_operation" => "Prepared a review in %<resource>s",
+        "propose_change" => "Prepared a review in %<resource>s",
+        "record_history" => "Read a record's history in %<resource>s"
+      }.freeze
+      # The line for a call whose stored result is an error (RAA-018).
+      FAILED_ACTIVITY = {
+        "list_resources" => "Tried to list the available resources",
+        "describe_resource" => "Tried to read the fields of %<resource>s",
+        "search_records" => "Tried to search %<resource>s",
+        "count_records" => "Tried to count records in %<resource>s",
+        "get_record" => "Tried to open a record in %<resource>s",
+        "propose_operation" => "Tried to prepare a review in %<resource>s",
+        "propose_change" => "Tried to prepare a review in %<resource>s",
+        "record_history" => "Tried to read a record's history in %<resource>s"
+      }.freeze
+      FAILURE_REASONS = {
+        "NOT_FOUND" => "not available", "INVALID_QUERY" => "the request was not valid", "CONFLICT" => "the record changed",
+        "VALIDATION_FAILED" => "the input was not valid", "UNAVAILABLE" => "not available"
+      }.freeze
+
+      def initialize(context, chat)
+        @context, @chat = context, chat
+      end
+
+      def entries
+        continuation_ids = @chat.turns.where(kind: "continuation").where.not(user_message_id: nil).pluck(:user_message_id).to_set
+        messages = @chat.messages.where.not(role: "system").includes(:ruby_llm_tool_calls, :ruby_llm_parent_tool_call)
+          .reorder(id: :desc).limit(MESSAGE_LIMIT).to_a.reverse
+        @results = messages.select { |message| message.role == "tool" && message.ruby_llm_parent_tool_call }
+          .to_h { |message| [ message.ruby_llm_parent_tool_call.id, message.content ] }
+        persisted = messages.flat_map do |message|
+          case message.role
+          when "user"
+            [ entry(continuation_ids.include?(message.id) ? :continuation : :user, message.content, message) ]
+          when "assistant"
+            activity = message.ruby_llm_tool_calls.map { |call| entry(:activity, activity_text(call), message) }
+            message.content.present? ? activity + [ entry(:assistant, message.content, message) ] : activity
+          when "tool" then tool_entries(message)
+          else []
+          end
+        end
+        persisted + waiting
+      end
+
+      private
+
+      # Saved turns whose human text the worker has not added to the chat yet,
+      # so a sent message shows at once instead of after the provider call.
+      def waiting
+        @chat.turns.where(status: Turn::ACTIVE, user_message_id: nil).reorder(:sequence).map do |turn|
+          Entry.new(turn.kind == "continuation" ? :continuation : :user, turn.content, [], nil, turn.created_at)
+        end
+      end
+
+      def entry(kind, text, message, links: [], surface_id: nil)
+        Entry.new(kind, text.to_s, links, surface_id, message.created_at)
+      end
+
+      # Derived from the stored result, so a failed call never reads as done.
+      def activity_text(call)
+        return "Used a tool" unless ACTIVITY.key?(call.name)
+        resource = resource_label(call.arguments.is_a?(Hash) ? call.arguments["resource"] : nil)
+        code = result_error(call)
+        return format(ACTIVITY.fetch(call.name), resource: resource) unless code
+        "#{format(FAILED_ACTIVITY.fetch(call.name), resource: resource)} (#{FAILURE_REASONS.fetch(code, 'not available')})"
+      end
+
+      def result_error(call)
+        data = JSON.parse(@results.fetch(call.id, nil).to_s)
+        data["error"].to_s if data.is_a?(Hash) && data["error"].is_a?(String)
+      rescue JSON::ParserError
+        nil
+      end
+
+      def resource_label(key)
+        resource = exposed(key)
+        resource ? resource.label : "a resource"
+      end
+
+      def exposed(key)
+        return unless key.is_a?(String)
+        resource = RailsAiAdmin.registry.fetch(key)
+        Authorization::Access.new(@context, resource).authorize_assistant!
+        resource
+      rescue AccessDenied, ConfigurationError, KeyError
+        nil
+      end
+
+      def tool_entries(message)
+        data = JSON.parse(message.content.to_s)
+        return [] unless data.is_a?(Hash)
+        if data["surface"].is_a?(String) && %w[propose_operation propose_change].include?(message.ruby_llm_parent_tool_call&.name)
+          return [ entry(:surface, nil, message, surface_id: data["surface"]) ]
+        end
+        links = record_links(data["resource"], data["records"])
+        links.empty? ? [] : [ entry(:records, nil, message, links: links) ]
+      rescue JSON::ParserError
+        []
+      end
+
+      # Only records the actor can still see, labelled through current grants.
+      def record_links(key, records)
+        resource = exposed(key)
+        return [] unless resource && records.is_a?(Array)
+        ids = records.first(LINK_LIMIT).filter_map { |record| record["id"] if record.is_a?(Hash) && record["id"].is_a?(String) }
+        return [] if ids.empty?
+        access = Authorization::Access.new(@context, resource)
+        found = access.relation.where(resource.model_class.primary_key => ids).index_by { |record| record.id.to_s }
+        ids.filter_map do |id|
+          record = found[id]
+          next unless record
+          access.authorize!(:show, record)
+          Link.new(resource.key.to_s, id, access.record_label(record))
+        rescue AccessDenied
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/rails_ai_admin/assistant.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module RailsAiAdmin
+  # Opt-in admin Chat on RubyLLM (ADR 0022). Loaded only when
+  # `config.assistant` is enabled, so conventional hosts never load RubyLLM.
+  module Assistant
+    class << self
+      def enabled? = RailsAiAdmin.configuration.assistant == true
+
+      # True when at least one registered resource is exposed to this actor.
+      def available?(context)
+        context.is_a?(Context) && RailsAiAdmin.registry.resources.any? do |resource|
+          Authorization::Access.new(context, resource).authorize_assistant!
+        rescue AccessDenied
+          false
+        end
+      end
+
+      # The host's per-request provider configuration. nil means the assistant
+      # is unavailable for this actor, which is a normal, recoverable state.
+      def llm_context(context)
+        adapter = RailsAiAdmin.configuration.assistant_adapter.constantize.new
+        raise ConfigurationError, "assistant_adapter must define llm_context(context:)" unless adapter.respond_to?(:llm_context)
+        value = adapter.llm_context(context: context)
+        return nil if value.nil?
+        raise ConfigurationError, "llm_context must return a RubyLLM::Context" unless value.is_a?(::RubyLLM::Context)
+        value
+      end
+
+      def create_chat!(context)
+        Chat.create!(ref: SecureRandom.uuid, actor_ref: context.actor_ref, tenant_ref: context.tenant_ref,
+          security_version: context.security_version, model: RailsAiAdmin.configuration.assistant_model,
+          provider: RailsAiAdmin.configuration.assistant_provider)
+      end
+
+      def tool_views
+        require "rails_ai_admin/integrations/tool_views"
+        Integrations::ToolViews
+      end
+    end
+  end
+end
+
+require "ruby_llm"
+require_relative "assistant/records"
+require_relative "assistant/tools"
+require_relative "assistant/runtime"
+require_relative "assistant/coordinator"
+require_relative "assistant/continuation"
+require_relative "assistant/transcript"